From 47c84a69f25fedc7ae5aa3766323d43d7c5db741 Mon Sep 17 00:00:00 2001 From: Michael Trestman Date: Thu, 20 Feb 2025 08:10:27 -0800 Subject: [PATCH 01/23] add btcli permissions table --- docs/btcli-permissions.md | 218 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 218 insertions(+) create mode 100644 docs/btcli-permissions.md diff --git a/docs/btcli-permissions.md b/docs/btcli-permissions.md new file mode 100644 index 00000000..87cc35dd --- /dev/null +++ b/docs/btcli-permissions.md @@ -0,0 +1,218 @@ +## Workstation config and wallet management + +Permissionless, but some wallet ops need the ck or hk (???) + +### `btcli config set` +### `btcli config get` +### `btcli config clear` +### `btcli config metagraph` +### `btcli conf set` +### `btcli conf get` +### `btcli conf clear` +### `btcli conf metagraph` + + +### `btcli c set` +### `btcli c get` +### `btcli c clear` +### `btcli c metagraph` + + + +### `btcli wallet list` +### `btcli wallet swap-hotkey` +### `btcli wallet regen-coldkey` +### `btcli wallet regen-coldkeypub` +### `btcli wallet regen-hotkey` +### `btcli wallet new-hotkey` +### `btcli wallet new-coldkey` +### `btcli wallet create` +### `btcli wallet balance` +### `btcli wallet history` +### `btcli wallet overview` +### `btcli wallet transfer` +### `btcli wallet inspect` +### `btcli wallet faucet` +### `btcli wallet set-identity` +### `btcli wallet get-identity` +### `btcli wallet sign` +### `btcli wallet swap_hotkey` +### `btcli wallet regen_coldkey` +### `btcli wallet regen_coldkeypub` +### `btcli wallet regen_hotkey` +### `btcli wallet new_hotkey` +### `btcli wallet new_coldkey` +### `btcli wallet set_identity` +### `btcli wallet get_identity` + + + +### `btcli w list` +### `btcli w swap-hotkey` +### `btcli w regen-coldkey` +### `btcli w regen-coldkeypub` +### `btcli w regen-hotkey` +### `btcli w new-hotkey` +### `btcli w new-coldkey` +### `btcli w create` +### `btcli w balance` +### `btcli w history` +### `btcli w overview` +### `btcli w transfer` +### `btcli w inspect` +### `btcli w faucet` +### `btcli w set-identity` +### `btcli w get-identity` +### `btcli w sign` +### `btcli w swap_hotkey` +### `btcli w regen_coldkey` +### `btcli w regen_coldkeypub` +### `btcli w regen_hotkey` +### `btcli w new_hotkey` +### `btcli w new_coldkey` +### `btcli w set_identity` +### `btcli w get_identity` +### `btcli wallets list` +### `btcli wallets swap-hotkey` +### `btcli wallets regen-coldkey` +### `btcli wallets regen-coldkeypub` +### `btcli wallets regen-hotkey` +### `btcli wallets new-hotkey` +### `btcli wallets new-coldkey` +### `btcli wallets create` +### `btcli wallets balance` +### `btcli wallets history` +### `btcli wallets overview` +### `btcli wallets transfer` +### `btcli wallets inspect` +### `btcli wallets faucet` +### `btcli wallets set-identity` +### `btcli wallets get-identity` +### `btcli wallets sign` +### `btcli wallets swap_hotkey` +### `btcli wallets regen_coldkey` +### `btcli wallets regen_coldkeypub` +### `btcli wallets regen_hotkey` +### `btcli wallets new_hotkey` +### `btcli wallets new_coldkey` +### `btcli wallets set_identity` +### `btcli wallets get_identity` + + + +## Stake Management + +Coldkey w sufficient TAO or w stake for unstaking/moving + + +### `btcli stake add` +### `btcli stake remove` +### `btcli stake list` +### `btcli stake move` +### `btcli stake transfer` +### `btcli stake swap` +### `btcli stake child` +#### `btcli stake child get` +#### `btcli stake child set` +#### `btcli stake child revoke` +#### `btcli stake child take` +### `btcli stake children` +#### `btcli stake children get` +#### `btcli stake children set` +#### `btcli stake children revoke` +#### `btcli stake children take` +### `btcli st add` +### `btcli st remove` +### `btcli st list` +### `btcli st move` +### `btcli st transfer` +### `btcli st swap` +### `btcli st child` +#### `btcli st child get` +#### `btcli st child set` +#### `btcli st child revoke` +#### `btcli st child take` +### `btcli st children` +#### `btcli st children get` +#### `btcli st children set` +#### `btcli st children revoke` +#### `btcli st children take` + + +## Subnet Management and Governance + +Setters need CK with creator permissions, getters are typically permissionsless (???) +Senate stuff: CK? have to be a Senator? (how does that work?) + +### `btcli sudo set` +### `btcli sudo get` +### `btcli sudo senate` +### `btcli sudo proposals` +### `btcli sudo senate-vote` +### `btcli sudo set-take` +### `btcli sudo get-take` +### `btcli sudo senate_vote` +### `btcli sudo get_take` +### `btcli sudo set_take` +### `btcli su set` +### `btcli su get` + + +### `btcli su senate` +### `btcli su proposals` +### `btcli su senate-vote` +### `btcli su set-take` +### `btcli su get-take` +### `btcli su senate_vote` +### `btcli su get_take` +### `btcli su set_take` + + +### `btcli subnets hyperparameters` +### `btcli subnets list` +### `btcli subnets burn-cost` +### `btcli subnets create` +### `btcli subnets pow-register` +### `btcli subnets register` +### `btcli subnets metagraph` +### `btcli subnets show` +### `btcli subnets price` +### `btcli subnets burn_cost` +### `btcli subnets pow_register` +### `btcli s hyperparameters` +### `btcli s list` +### `btcli s burn-cost` +### `btcli s create` +### `btcli s pow-register` +### `btcli s register` +### `btcli s metagraph` +### `btcli s show` +### `btcli s price` +### `btcli s burn_cost` +### `btcli s pow_register` +### `btcli subnet hyperparameters` +### `btcli subnet list` +### `btcli subnet burn-cost` +### `btcli subnet create` +### `btcli subnet pow-register` +### `btcli subnet register` +### `btcli subnet metagraph` +### `btcli subnet show` +### `btcli subnet price` +### `btcli subnet burn_cost` +### `btcli subnet pow_register` +### `btcli weights reveal` +### `btcli weights commit` + +## Weights + +Setters require HK w validator permit. getters permissionless (???) + +### `btcli wt reveal` +### `btcli wt commit` +### `btcli weight reveal` +### `btcli weight commit` + +## Utils ??? + +### `btcli utils convert` \ No newline at end of file From ffbbe458e48a5f1eaf52b8101ac1c44347fa8241 Mon Sep 17 00:00:00 2001 From: Michael Trestman Date: Thu, 20 Feb 2025 08:15:29 -0800 Subject: [PATCH 02/23] wip --- docs/btcli-permissions.md | 12 ++++++++++-- 1 file changed, 10 insertions(+), 2 deletions(-) diff --git a/docs/btcli-permissions.md b/docs/btcli-permissions.md index 87cc35dd..0de904e6 100644 --- a/docs/btcli-permissions.md +++ b/docs/btcli-permissions.md @@ -1,7 +1,10 @@ -## Workstation config and wallet management +## Workstation config Permissionless, but some wallet ops need the ck or hk (???) + + + ### `btcli config set` ### `btcli config get` ### `btcli config clear` @@ -17,6 +20,10 @@ Permissionless, but some wallet ops need the ck or hk (???) ### `btcli c clear` ### `btcli c metagraph` +## wallet management + + +Mostly target a coldkey; should be performed on a max CK workstation, NOT a mining workstation or any other insecure endpoint. ### `btcli wallet list` @@ -46,7 +53,6 @@ Permissionless, but some wallet ops need the ck or hk (???) ### `btcli wallet get_identity` - ### `btcli w list` ### `btcli w swap-hotkey` ### `btcli w regen-coldkey` @@ -104,6 +110,8 @@ Permissionless, but some wallet ops need the ck or hk (???) Coldkey w sufficient TAO or w stake for unstaking/moving +Mostly target a coldkey; should be performed on a max CK workstation, NOT a mining workstation or any other insecure endpoint. + ### `btcli stake add` ### `btcli stake remove` From 2a6aa69be41a6b85abd3da1ef4a01a0e815caa83 Mon Sep 17 00:00:00 2001 From: Michael Trestman Date: Thu, 20 Feb 2025 08:19:50 -0800 Subject: [PATCH 03/23] wip --- docs/btcli-permissions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/btcli-permissions.md b/docs/btcli-permissions.md index 0de904e6..31b80798 100644 --- a/docs/btcli-permissions.md +++ b/docs/btcli-permissions.md @@ -150,7 +150,7 @@ Mostly target a coldkey; should be performed on a max CK workstation, NOT a mini ## Subnet Management and Governance Setters need CK with creator permissions, getters are typically permissionsless (???) -Senate stuff: CK? have to be a Senator? (how does that work?) +Senate stuff: CK? have to be a [Senator](./senate#requirements) ### `btcli sudo set` ### `btcli sudo get` From 65eaae6c039128baa6e09124f080f45d9d9f9bf1 Mon Sep 17 00:00:00 2001 From: Michael Trestman Date: Thu, 20 Feb 2025 08:22:16 -0800 Subject: [PATCH 04/23] wip --- docs/btcli-permissions.md | 14 ++++---------- 1 file changed, 4 insertions(+), 10 deletions(-) diff --git a/docs/btcli-permissions.md b/docs/btcli-permissions.md index 31b80798..e26615d6 100644 --- a/docs/btcli-permissions.md +++ b/docs/btcli-permissions.md @@ -2,9 +2,6 @@ Permissionless, but some wallet ops need the ck or hk (???) - - - ### `btcli config set` ### `btcli config get` ### `btcli config clear` @@ -14,17 +11,16 @@ Permissionless, but some wallet ops need the ck or hk (???) ### `btcli conf clear` ### `btcli conf metagraph` - ### `btcli c set` ### `btcli c get` ### `btcli c clear` ### `btcli c metagraph` -## wallet management -Mostly target a coldkey; should be performed on a max CK workstation, NOT a mining workstation or any other insecure endpoint. +## Wallet management +Mostly target a coldkey; should be performed on a max CK workstation, NOT a mining workstation or any other insecure endpoint. ### `btcli wallet list` ### `btcli wallet swap-hotkey` @@ -52,7 +48,6 @@ Mostly target a coldkey; should be performed on a max CK workstation, NOT a mini ### `btcli wallet set_identity` ### `btcli wallet get_identity` - ### `btcli w list` ### `btcli w swap-hotkey` ### `btcli w regen-coldkey` @@ -112,7 +107,6 @@ Coldkey w sufficient TAO or w stake for unstaking/moving Mostly target a coldkey; should be performed on a max CK workstation, NOT a mining workstation or any other insecure endpoint. - ### `btcli stake add` ### `btcli stake remove` ### `btcli stake list` @@ -165,7 +159,6 @@ Senate stuff: CK? have to be a [Senator](./senate#requirements) ### `btcli su set` ### `btcli su get` - ### `btcli su senate` ### `btcli su proposals` ### `btcli su senate-vote` @@ -175,7 +168,6 @@ Senate stuff: CK? have to be a [Senator](./senate#requirements) ### `btcli su get_take` ### `btcli su set_take` - ### `btcli subnets hyperparameters` ### `btcli subnets list` ### `btcli subnets burn-cost` @@ -212,6 +204,7 @@ Senate stuff: CK? have to be a [Senator](./senate#requirements) ### `btcli weights reveal` ### `btcli weights commit` + ## Weights Setters require HK w validator permit. getters permissionless (???) @@ -221,6 +214,7 @@ Setters require HK w validator permit. getters permissionless (???) ### `btcli weight reveal` ### `btcli weight commit` + ## Utils ??? ### `btcli utils convert` \ No newline at end of file From 35ad6d663c14137c77cfe5d9014ea09d4b0cfd5d Mon Sep 17 00:00:00 2001 From: Michael Trestman Date: Thu, 20 Feb 2025 08:30:52 -0800 Subject: [PATCH 05/23] wip --- docs/btcli-permissions.md | 16 +++++++++++----- 1 file changed, 11 insertions(+), 5 deletions(-) diff --git a/docs/btcli-permissions.md b/docs/btcli-permissions.md index e26615d6..fc64f442 100644 --- a/docs/btcli-permissions.md +++ b/docs/btcli-permissions.md @@ -17,10 +17,11 @@ Permissionless, but some wallet ops need the ck or hk (???) ### `btcli c metagraph` - ## Wallet management -Mostly target a coldkey; should be performed on a max CK workstation, NOT a mining workstation or any other insecure endpoint. +Mostly target a coldkey; should be performed on a secure CK workstation, NOT a mining workstation or any other insecure endpoint. + +HKs should be created on secure CK workstation and then carefully provisioned to less secure working nodes for mining and validation. ### `btcli wallet list` ### `btcli wallet swap-hotkey` @@ -100,12 +101,11 @@ Mostly target a coldkey; should be performed on a max CK workstation, NOT a mini ### `btcli wallets get_identity` - ## Stake Management Coldkey w sufficient TAO or w stake for unstaking/moving -Mostly target a coldkey; should be performed on a max CK workstation, NOT a mining workstation or any other insecure endpoint. +Mostly target a coldkey; should be performed on a secure CK workstation, NOT a mining workstation or any other insecure endpoint. ### `btcli stake add` ### `btcli stake remove` @@ -143,9 +143,15 @@ Mostly target a coldkey; should be performed on a max CK workstation, NOT a mini ## Subnet Management and Governance -Setters need CK with creator permissions, getters are typically permissionsless (???) +Complicated! + +Subnet management: Setters need CK with creator permissions, getters are typically permissionsless (???) + Senate stuff: CK? have to be a [Senator](./senate#requirements) +miner/validator registration stuff: setters HK, but getters permissionless or maybe HK? + + ### `btcli sudo set` ### `btcli sudo get` ### `btcli sudo senate` From 559d54d91bcceb50532957ea208a6e6f9f0d7816 Mon Sep 17 00:00:00 2001 From: Michael Trestman Date: Thu, 20 Feb 2025 08:32:19 -0800 Subject: [PATCH 06/23] wip --- docs/btcli-permissions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/btcli-permissions.md b/docs/btcli-permissions.md index fc64f442..fc19e158 100644 --- a/docs/btcli-permissions.md +++ b/docs/btcli-permissions.md @@ -1,6 +1,6 @@ ## Workstation config -Permissionless, but some wallet ops need the ck or hk (???) +Permissionless ### `btcli config set` ### `btcli config get` From ae46dd2e048a8afdf514ce8de45caf3b4b37ec27 Mon Sep 17 00:00:00 2001 From: Michael Trestman Date: Sun, 23 Feb 2025 10:43:00 -0800 Subject: [PATCH 07/23] wip --- docs/btcli-permissions.md | 36 +++++++++++++++++++++++------------- 1 file changed, 23 insertions(+), 13 deletions(-) diff --git a/docs/btcli-permissions.md b/docs/btcli-permissions.md index fc19e158..4bd1fc73 100644 --- a/docs/btcli-permissions.md +++ b/docs/btcli-permissions.md @@ -1,21 +1,31 @@ + ## Workstation config -Permissionless +
+ btcli config -### `btcli config set` -### `btcli config get` -### `btcli config clear` -### `btcli config metagraph` -### `btcli conf set` -### `btcli conf get` -### `btcli conf clear` -### `btcli conf metagraph` + btcli config [options] + - btcli config set + - btcli config get + - ... + - btcli conf metagraph -### `btcli c set` -### `btcli c get` -### `btcli c clear` -### `btcli c metagraph` +Permissionless +- `btcli config set` +- `btcli config get` +- `btcli config clear` +- `btcli config metagraph` +- `btcli conf set` +- `btcli conf get` +- `btcli conf clear` +- `btcli conf metagraph` + +- `btcli c set` +- `btcli c get` +- `btcli c clear` +- `btcli c metagraph` +
## Wallet management From 33847c8d3de7da9262aa843b78aaa81cb535cb1e Mon Sep 17 00:00:00 2001 From: Michael Trestman Date: Mon, 3 Mar 2025 12:37:55 -0800 Subject: [PATCH 08/23] wip --- docs/btcli-permissions.md | 43 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 43 insertions(+) diff --git a/docs/btcli-permissions.md b/docs/btcli-permissions.md index 4bd1fc73..fd332339 100644 --- a/docs/btcli-permissions.md +++ b/docs/btcli-permissions.md @@ -1,6 +1,49 @@ +--- +title: "Bittensor CLI: Permissions Guide" +--- + +The Bittensor CLI, `btcli` provides a wide range of functionality: some commands require a coldkey to authenticate, some require a hotkey, and some require neither. Additionally, different functions require different levels of permissions. Some require the user to have special status like being registered with a node, have a validator permit, or be an active member of the senate. + +This page details the requirements for all of the `btcli` commands. It is organized by Bittensor *persona*, on the assumption that everyone who uses `btcli` is in one or more of the following roles: + +- stakers: +- miners: +- validators: +- subnet creators: +- governance: + + +## Stakers + +Stakers enter value into the Bittensor network by acquiring TAO and staking or *delegating* it to validators to support their work. As validators extract emissions, a certain percentage goes back to stakers. + +See [Staking/Delegation Overview](../staking-and-delegation/delegation.md). + +Stakers must be familiar with operations related to managing the TAO and staked alpha tokens in their Bittensor wallet balance. + +Performing these functions requires using a coldkey, and hence must be performed in a highly secure environment for any wallet connected to real (mainnet) TAO balance. + +Accounts can be viewed without using a coldkey... + +## Miners + +## Validators + +## Subnet Creators + +## Requirements: + +### Coldkey +### Hotkey + +### Available liquidity + +### Validator Permit ## Workstation config + +
btcli config From 9b59040044f447931d8f75c9a4a77b090d776f16 Mon Sep 17 00:00:00 2001 From: Michael Trestman Date: Mon, 3 Mar 2025 18:04:55 -0800 Subject: [PATCH 09/23] wip --- docs/btcli-permissions.md | 2 +- sidebars.js | 1 + 2 files changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/btcli-permissions.md b/docs/btcli-permissions.md index fd332339..4f299a67 100644 --- a/docs/btcli-permissions.md +++ b/docs/btcli-permissions.md @@ -17,7 +17,7 @@ This page details the requirements for all of the `btcli` commands. It is organi Stakers enter value into the Bittensor network by acquiring TAO and staking or *delegating* it to validators to support their work. As validators extract emissions, a certain percentage goes back to stakers. -See [Staking/Delegation Overview](../staking-and-delegation/delegation.md). +See [Staking/Delegation Overview](./staking-and-delegation/delegation.md). Stakers must be familiar with operations related to managing the TAO and staked alpha tokens in their Bittensor wallet balance. diff --git a/sidebars.js b/sidebars.js index 595acd1b..e2144567 100644 --- a/sidebars.js +++ b/sidebars.js @@ -111,6 +111,7 @@ const sidebars = { "getting-started/install-btcli", "btcli", "staking-and-delegation/managing-stake-btcli", + "btcli-permissions" ] }, { From 5436319042e5d3caeea5d030b4338f27f725b79b Mon Sep 17 00:00:00 2001 From: Michael Trestman Date: Mon, 3 Mar 2025 18:18:53 -0800 Subject: [PATCH 10/23] wip --- docs/btcli-permissions.md | 124 ++++++++++++++++++++++++++++++++++---- 1 file changed, 113 insertions(+), 11 deletions(-) diff --git a/docs/btcli-permissions.md b/docs/btcli-permissions.md index 4f299a67..065866b7 100644 --- a/docs/btcli-permissions.md +++ b/docs/btcli-permissions.md @@ -12,6 +12,9 @@ This page details the requirements for all of the `btcli` commands. It is organi - subnet creators: - governance: +:::info +For additional background on the difference between **coldkeys** and **hotkeys**, please refer to the [Wallets, Coldkeys and Hotkeys in Bittensor](#wallets-coldkeys-and-hotkeys-in-bittensor-reference) section below (summarized from [the separate doc](./working-with-keys.md)). +::: ## Stakers @@ -21,28 +24,128 @@ See [Staking/Delegation Overview](./staking-and-delegation/delegation.md). Stakers must be familiar with operations related to managing the TAO and staked alpha tokens in their Bittensor wallet balance. -Performing these functions requires using a coldkey, and hence must be performed in a highly secure environment for any wallet connected to real (mainnet) TAO balance. +Performing these functions requires using a **coldkey**, and hence must be performed in a **highly secure environment** for any wallet connected to real (mainnet) TAO balance. A leak of your coldkey can lead to a catastrophic loss of funds. -Accounts can be viewed without using a coldkey... +Accounts can be viewed without using a coldkey, but any changes to stake, transfers, or delegations require signing with the coldkey. + +### Commands most relevant to stakers: +- **Wallet Commands** (Coldkey required for modifications): + - `btcli wallet create`, `btcli wallet new-coldkey`, `btcli wallet new_coldkey`: Create or generate a new coldkey (secure environment). + - `btcli wallet balance`, `btcli wallet overview`, `btcli wallet history`: View balances and transaction history. Viewing does not require a coldkey *if* you only query public chain state, but typically you’ll specify the coldkey to reference your own account data. + - `btcli wallet transfer`: Transfer TAO from your coldkey to another address. Requires a coldkey signature (secure environment). + - `btcli wallet faucet`: (Testnet only or any environment with a faucet). Coldkey not necessarily required if the faucet only needs a public key, but typically you’ll manage it via your wallet. + - `btcli wallet inspect`: Inspect wallet details (permissionless unless you want to do private key operations). +- **Stake Management** (All require **coldkey** in a secure environment): + - `btcli stake add`, `btcli stake remove`, `btcli stake list`, `btcli stake move`, `btcli stake transfer`, `btcli stake swap` + - `btcli stake child ...` / `btcli stake children ...` (get, set, revoke, take) + - Short aliases: `btcli st add`, `btcli st remove`, etc. + +In summary, **stakers only need a coldkey**. Staking commands should **never** be run on an insecure or public-facing machine since the coldkey manages your TAO holdings. ## Miners +Miners run processes that serve or forward inference requests on the network. They register with the chain using a **hotkey** to obtain a UID for the subnet(s) in which they operate. + +- Hotkey creation can be done on a secure machine (paired with your coldkey). **However, day-to-day mining** is done with the hotkey in a less secure environment (the “mining rig” or server), since it needs to be online to serve inference requests. +- Miners *can* also stake TAO, but that typically requires using the coldkey in a secure environment to move or delegate stake. Once staked, the miner can remain on their hotkey-based environment to continue operation. + +### Commands most relevant to miners: +- **Subnet Registration / Info**: + - `btcli subnets list`, `btcli subnets show`, `btcli subnets metagraph`: Generally permissionless *reads* to see available subnets or node info. + - `btcli subnets price`, `btcli subnets burn-cost`, `btcli subnets burn_cost`: Show the required burn to register in a particular subnet. Permissionless read. + - `btcli subnets pow-register`, `btcli subnets pow_register`, `btcli subnets register`: Miner uses these to register themselves on the subnet, typically from a machine with the hotkey. **However,** the associated transaction cost must come from the coldkey. So you either sign it with your coldkey (secure environment) or set up a valid signature flow. + - The **registration** places the hotkey on the chain with a UID in that subnet. +- **Wallet**: + - `btcli wallet new-hotkey` / `btcli wallet regen-hotkey`: Creation/regeneration of hotkeys. Typically do these on a secure machine (paired to your coldkey), then transfer the hotkey file or mnemonic to the mining machine. + - `btcli wallet balance` and `btcli wallet overview`: Might be used to check the hotkey’s on-chain state or small balances. (Hotkey on a less secure machine is lower risk, but still treat it with caution.) +- **Config**: + - `btcli config set`, `btcli config get`, etc. (Permissionless) to configure endpoints or chain settings as you run a miner. + +Miners primarily rely on **hotkeys** for daily operations. The **coldkey** is only needed when you need to create or fund that hotkey, or if you want to stake additional TAO or pay the burn for certain registrations. + ## Validators +Validators secure the network by finalizing blocks, validating miner performance, and posting “weights” that reflect consensus on performance. In Bittensor’s design: +- **Hotkey** (with a validator permit) signs and submits “weight” extrinsics, typically from a machine that is online and runs the validator logic. +- **Coldkey** is needed for any stake management or large fund transfers. + +### Commands most relevant to validators: +- **Weights**: + - `btcli weights reveal`, `btcli weights commit` + - `btcli wt reveal`, `btcli wt commit` + - `btcli weight reveal`, `btcli weight commit` + These require a hotkey with an on-chain validator permit. Typically run in a live environment (the validator node). +- **Stake Management** (if you stake TAO to your validator hotkey or accept delegations): + - `btcli stake add`, `btcli stake remove`, `btcli stake move`, etc. (see [Stakers](#stakers) section). + Requires the coldkey in a **secure environment** if you are adding or removing stake from your own coldkey to your validator hotkey. +- **Subnet Registration**: + - If you are validating on a particular subnet, you often must register with `btcli subnets register` or `btcli subnets pow-register`, same as miners. This also typically involves your coldkey to pay any required fees, while awarding your hotkey the validator status/UID in that subnet. + +In short, validators use their **hotkey** for daily validation and weights. The coldkey is still needed for any staking or managing TAO, so you keep it offline or in a more secure environment whenever possible. + ## Subnet Creators +Subnet creators define and manage new subnets, specifying parameters like burn cost, hyperparameters, or other chain-level configurations. This role inherently requires a **coldkey** with sufficient balance/permissions to create or update subnets. + +### Commands most relevant to subnet creators: +- **Subnet Creation / Configuration** (all require **coldkey** in a secure environment to sign on-chain transactions): + - `btcli subnets create` + - `btcli subnets hyperparameters` + - `btcli subnets burn-cost` / `btcli subnets burn_cost` + - `btcli subnets price` + - `btcli subnets set` (some advanced usage might come in via `sudo` or governance commands) + - Similarly, short forms like `btcli s create`, `btcli s burn-cost`, `btcli subnet create`, etc. +- **Reads** (permissionless in many cases): + - `btcli subnets list`, `btcli subnets show`, `btcli subnets metagraph` + - The short forms `btcli s list`, `btcli s show`, `btcli subnet list`, and so on. + +The core difference is that *creating* or *altering* a subnet’s parameters requires a secure environment and a coldkey that has enough TAO and the appropriate on-chain privileges. + +## Governance Functions + +Governance participants (senate members, sudo-level accounts) can propose changes, cast votes, or execute privileged commands that affect the entire network. They must have a **coldkey** with the relevant governance role (senate membership or sudo privileges). + +### Commands most relevant to governance: + +- **Senate / Proposals** (coldkey with senator role): + - `btcli sudo senate` + - `btcli sudo proposals` + - `btcli sudo senate-vote` + - `btcli sudo senate_vote` + - Aliases: `btcli su senate`, `btcli su proposals`, etc. +- **Sudo Commands** (coldkey with sudo privileges): + - `btcli sudo set`, `btcli sudo get` + - `btcli sudo set-take`, `btcli sudo get-take` + - `btcli sudo set_take`, `btcli sudo get_take` + - Aliases: `btcli su set`, `btcli su get`, etc. + +Because these commands can significantly change chain parameters or enact critical changes, they require a fully privileged coldkey in a **very** secure environment. + ## Requirements: ### Coldkey +Your primary, fully privileged key. Required for: +- Managing stake (add/remove/move). +- Moving or transferring TAO (i.e., `wallet transfer`). +- Creating or modifying subnets (`btcli subnets create`). +- Voting or proposing in governance. +Must be used on a **high-security machine** to avoid catastrophic loss if compromised. + ### Hotkey +Used for daily operations with lower privileges: +- Running miners (signing inference, staying online). +- Running validators (weight commits, daily on-chain actions). +Usually stored on a less secure environment than the coldkey because it must be online and accessible for repeated use. ### Available liquidity +Make sure your coldkey wallet has sufficient on-chain TAO to pay fees, stake, or register subnets. Insufficient balance will cause transactions to fail. ### Validator Permit +An on-chain permission required for hotkeys that want to operate as validators. Without it, you can’t sign or submit weight commits. ## Workstation config - - +- **Coldkey workstation**: Minimal exposure, ideally offline or with strong security controls. Used only for signing critical transactions (e.g., staking, governance, subnet creation). +- **Hotkey workstation**: Online servers used for mining or validation. Contains only hotkeys.
btcli config @@ -153,7 +256,6 @@ HKs should be created on secure CK workstation and then carefully provisioned to ### `btcli wallets set_identity` ### `btcli wallets get_identity` - ## Stake Management Coldkey w sufficient TAO or w stake for unstaking/moving @@ -198,12 +300,11 @@ Mostly target a coldkey; should be performed on a secure CK workstation, NOT a m Complicated! -Subnet management: Setters need CK with creator permissions, getters are typically permissionsless (???) - -Senate stuff: CK? have to be a [Senator](./senate#requirements) +Subnet management: Setters need CK with creator permissions, getters are typically permissionless (for listing or reading). Creating or modifying subnets (burn cost, price, hyperparameters) requires a coldkey with sufficient balance and permissions. -miner/validator registration stuff: setters HK, but getters permissionless or maybe HK? +Senate stuff: CK with senator role for proposals and votes, or CK with sudo privileges for certain chain-level commands. +miner/validator registration stuff: typically uses a hotkey for the registration extrinsic, though the creation of subnets (which set registration parameters) requires a coldkey. ### `btcli sudo set` ### `btcli sudo get` @@ -266,7 +367,7 @@ miner/validator registration stuff: setters HK, but getters permissionless or ma ## Weights -Setters require HK w validator permit. getters permissionless (???) +Setters require an active hotkey that has a validator permit. Reading or querying weights is generally permissionless, but committing or revealing them is only for registered validators. ### `btcli wt reveal` ### `btcli wt commit` @@ -276,4 +377,5 @@ Setters require HK w validator permit. getters permissionless (???) ## Utils ??? -### `btcli utils convert` \ No newline at end of file +### `btcli utils convert` +This is a convenience command for performing conversions between minimal units (RAO) and TAO, or other chain-specific conversions. Permissionless (no key required) because it performs no on-chain operation, just a local calculation. From 5d18a315960301cac01ba9bc97b2ba3f8d60f23c Mon Sep 17 00:00:00 2001 From: Michael Trestman Date: Mon, 3 Mar 2025 18:24:35 -0800 Subject: [PATCH 11/23] wip --- docs/btcli-permissions.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/btcli-permissions.md b/docs/btcli-permissions.md index 065866b7..7f822a1f 100644 --- a/docs/btcli-permissions.md +++ b/docs/btcli-permissions.md @@ -39,6 +39,11 @@ Accounts can be viewed without using a coldkey, but any changes to stake, transf - `btcli stake add`, `btcli stake remove`, `btcli stake list`, `btcli stake move`, `btcli stake transfer`, `btcli stake swap` - `btcli stake child ...` / `btcli stake children ...` (get, set, revoke, take) - Short aliases: `btcli st add`, `btcli st remove`, etc. +- **Subnet Discovery**: + - `btcli subnets list`, `btcli subnets show`, `btcli subnets metagraph`: Permissionless *reads* to see available subnets or node info. + - `btcli subnets price`, `btcli subnets burn-cost`, `btcli subnets burn_cost`: Show the required burn to register in a particular subnet. Permissionless read. +- **Config**: + - `btcli config set`, `btcli config get`, etc. (Permissionless) to configure a `btcli` environment. In summary, **stakers only need a coldkey**. Staking commands should **never** be run on an insecure or public-facing machine since the coldkey manages your TAO holdings. @@ -49,17 +54,12 @@ Miners run processes that serve or forward inference requests on the network. Th - Hotkey creation can be done on a secure machine (paired with your coldkey). **However, day-to-day mining** is done with the hotkey in a less secure environment (the “mining rig” or server), since it needs to be online to serve inference requests. - Miners *can* also stake TAO, but that typically requires using the coldkey in a secure environment to move or delegate stake. Once staked, the miner can remain on their hotkey-based environment to continue operation. -### Commands most relevant to miners: -- **Subnet Registration / Info**: - - `btcli subnets list`, `btcli subnets show`, `btcli subnets metagraph`: Generally permissionless *reads* to see available subnets or node info. - - `btcli subnets price`, `btcli subnets burn-cost`, `btcli subnets burn_cost`: Show the required burn to register in a particular subnet. Permissionless read. +### Additional Commands most relevant to miners: - `btcli subnets pow-register`, `btcli subnets pow_register`, `btcli subnets register`: Miner uses these to register themselves on the subnet, typically from a machine with the hotkey. **However,** the associated transaction cost must come from the coldkey. So you either sign it with your coldkey (secure environment) or set up a valid signature flow. - The **registration** places the hotkey on the chain with a UID in that subnet. - **Wallet**: - `btcli wallet new-hotkey` / `btcli wallet regen-hotkey`: Creation/regeneration of hotkeys. Typically do these on a secure machine (paired to your coldkey), then transfer the hotkey file or mnemonic to the mining machine. - `btcli wallet balance` and `btcli wallet overview`: Might be used to check the hotkey’s on-chain state or small balances. (Hotkey on a less secure machine is lower risk, but still treat it with caution.) -- **Config**: - - `btcli config set`, `btcli config get`, etc. (Permissionless) to configure endpoints or chain settings as you run a miner. Miners primarily rely on **hotkeys** for daily operations. The **coldkey** is only needed when you need to create or fund that hotkey, or if you want to stake additional TAO or pay the burn for certain registrations. From 6e892c120f0a54002720daa44af9abca4eaba556 Mon Sep 17 00:00:00 2001 From: Michael Trestman Date: Mon, 3 Mar 2025 22:13:48 -0800 Subject: [PATCH 12/23] wip --- docs/btcli-permissions.md | 513 ++++++++---------- docs/governance/senators-btcli-guide.md | 32 ++ docs/miners/miners-btcli-guide.md | 26 + .../stakers-btcli-guide.md | 35 ++ docs/subnets/subnet-creators-btcli-guide.md | 28 + docs/validators/validators-btcli-guide.md | 45 ++ sidebars.js | 7 +- 7 files changed, 386 insertions(+), 300 deletions(-) create mode 100644 docs/governance/senators-btcli-guide.md create mode 100644 docs/miners/miners-btcli-guide.md create mode 100644 docs/staking-and-delegation/stakers-btcli-guide.md create mode 100644 docs/subnets/subnet-creators-btcli-guide.md create mode 100644 docs/validators/validators-btcli-guide.md diff --git a/docs/btcli-permissions.md b/docs/btcli-permissions.md index 7f822a1f..5f5af7af 100644 --- a/docs/btcli-permissions.md +++ b/docs/btcli-permissions.md @@ -4,124 +4,24 @@ title: "Bittensor CLI: Permissions Guide" The Bittensor CLI, `btcli` provides a wide range of functionality: some commands require a coldkey to authenticate, some require a hotkey, and some require neither. Additionally, different functions require different levels of permissions. Some require the user to have special status like being registered with a node, have a validator permit, or be an active member of the senate. -This page details the requirements for all of the `btcli` commands. It is organized by Bittensor *persona*, on the assumption that everyone who uses `btcli` is in one or more of the following roles: +This page details the requirements for all of the `btcli` commands. + +See also the `btcli` permissions guides for specific Bittensor personas: + +- [Staker's Guide to `BTCLI`](./staking-and-delegation/stakers-btcli-guide) +- [Miner's Guide to `BTCLI`](./miners/miners-btcli-guide) +- [Validator's Guide to `BTCLI`](./validators/validators-btcli-guide) +- [Subnet Creator's Guide to `BTCLI`](./subnets/subnet-creators-btcli-guide) +- [Senator's Guide to `BTCLI`](./governance/senators-btcli-guide) -- stakers: -- miners: -- validators: -- subnet creators: -- governance: :::info For additional background on the difference between **coldkeys** and **hotkeys**, please refer to the [Wallets, Coldkeys and Hotkeys in Bittensor](#wallets-coldkeys-and-hotkeys-in-bittensor-reference) section below (summarized from [the separate doc](./working-with-keys.md)). ::: -## Stakers - -Stakers enter value into the Bittensor network by acquiring TAO and staking or *delegating* it to validators to support their work. As validators extract emissions, a certain percentage goes back to stakers. - -See [Staking/Delegation Overview](./staking-and-delegation/delegation.md). - -Stakers must be familiar with operations related to managing the TAO and staked alpha tokens in their Bittensor wallet balance. - -Performing these functions requires using a **coldkey**, and hence must be performed in a **highly secure environment** for any wallet connected to real (mainnet) TAO balance. A leak of your coldkey can lead to a catastrophic loss of funds. - -Accounts can be viewed without using a coldkey, but any changes to stake, transfers, or delegations require signing with the coldkey. - -### Commands most relevant to stakers: -- **Wallet Commands** (Coldkey required for modifications): - - `btcli wallet create`, `btcli wallet new-coldkey`, `btcli wallet new_coldkey`: Create or generate a new coldkey (secure environment). - - `btcli wallet balance`, `btcli wallet overview`, `btcli wallet history`: View balances and transaction history. Viewing does not require a coldkey *if* you only query public chain state, but typically you’ll specify the coldkey to reference your own account data. - - `btcli wallet transfer`: Transfer TAO from your coldkey to another address. Requires a coldkey signature (secure environment). - - `btcli wallet faucet`: (Testnet only or any environment with a faucet). Coldkey not necessarily required if the faucet only needs a public key, but typically you’ll manage it via your wallet. - - `btcli wallet inspect`: Inspect wallet details (permissionless unless you want to do private key operations). -- **Stake Management** (All require **coldkey** in a secure environment): - - `btcli stake add`, `btcli stake remove`, `btcli stake list`, `btcli stake move`, `btcli stake transfer`, `btcli stake swap` - - `btcli stake child ...` / `btcli stake children ...` (get, set, revoke, take) - - Short aliases: `btcli st add`, `btcli st remove`, etc. -- **Subnet Discovery**: - - `btcli subnets list`, `btcli subnets show`, `btcli subnets metagraph`: Permissionless *reads* to see available subnets or node info. - - `btcli subnets price`, `btcli subnets burn-cost`, `btcli subnets burn_cost`: Show the required burn to register in a particular subnet. Permissionless read. -- **Config**: - - `btcli config set`, `btcli config get`, etc. (Permissionless) to configure a `btcli` environment. - -In summary, **stakers only need a coldkey**. Staking commands should **never** be run on an insecure or public-facing machine since the coldkey manages your TAO holdings. - -## Miners - -Miners run processes that serve or forward inference requests on the network. They register with the chain using a **hotkey** to obtain a UID for the subnet(s) in which they operate. - -- Hotkey creation can be done on a secure machine (paired with your coldkey). **However, day-to-day mining** is done with the hotkey in a less secure environment (the “mining rig” or server), since it needs to be online to serve inference requests. -- Miners *can* also stake TAO, but that typically requires using the coldkey in a secure environment to move or delegate stake. Once staked, the miner can remain on their hotkey-based environment to continue operation. - -### Additional Commands most relevant to miners: - - `btcli subnets pow-register`, `btcli subnets pow_register`, `btcli subnets register`: Miner uses these to register themselves on the subnet, typically from a machine with the hotkey. **However,** the associated transaction cost must come from the coldkey. So you either sign it with your coldkey (secure environment) or set up a valid signature flow. - - The **registration** places the hotkey on the chain with a UID in that subnet. -- **Wallet**: - - `btcli wallet new-hotkey` / `btcli wallet regen-hotkey`: Creation/regeneration of hotkeys. Typically do these on a secure machine (paired to your coldkey), then transfer the hotkey file or mnemonic to the mining machine. - - `btcli wallet balance` and `btcli wallet overview`: Might be used to check the hotkey’s on-chain state or small balances. (Hotkey on a less secure machine is lower risk, but still treat it with caution.) - -Miners primarily rely on **hotkeys** for daily operations. The **coldkey** is only needed when you need to create or fund that hotkey, or if you want to stake additional TAO or pay the burn for certain registrations. - -## Validators - -Validators secure the network by finalizing blocks, validating miner performance, and posting “weights” that reflect consensus on performance. In Bittensor’s design: -- **Hotkey** (with a validator permit) signs and submits “weight” extrinsics, typically from a machine that is online and runs the validator logic. -- **Coldkey** is needed for any stake management or large fund transfers. - -### Commands most relevant to validators: -- **Weights**: - - `btcli weights reveal`, `btcli weights commit` - - `btcli wt reveal`, `btcli wt commit` - - `btcli weight reveal`, `btcli weight commit` - These require a hotkey with an on-chain validator permit. Typically run in a live environment (the validator node). -- **Stake Management** (if you stake TAO to your validator hotkey or accept delegations): - - `btcli stake add`, `btcli stake remove`, `btcli stake move`, etc. (see [Stakers](#stakers) section). - Requires the coldkey in a **secure environment** if you are adding or removing stake from your own coldkey to your validator hotkey. -- **Subnet Registration**: - - If you are validating on a particular subnet, you often must register with `btcli subnets register` or `btcli subnets pow-register`, same as miners. This also typically involves your coldkey to pay any required fees, while awarding your hotkey the validator status/UID in that subnet. - -In short, validators use their **hotkey** for daily validation and weights. The coldkey is still needed for any staking or managing TAO, so you keep it offline or in a more secure environment whenever possible. - -## Subnet Creators - -Subnet creators define and manage new subnets, specifying parameters like burn cost, hyperparameters, or other chain-level configurations. This role inherently requires a **coldkey** with sufficient balance/permissions to create or update subnets. - -### Commands most relevant to subnet creators: -- **Subnet Creation / Configuration** (all require **coldkey** in a secure environment to sign on-chain transactions): - - `btcli subnets create` - - `btcli subnets hyperparameters` - - `btcli subnets burn-cost` / `btcli subnets burn_cost` - - `btcli subnets price` - - `btcli subnets set` (some advanced usage might come in via `sudo` or governance commands) - - Similarly, short forms like `btcli s create`, `btcli s burn-cost`, `btcli subnet create`, etc. -- **Reads** (permissionless in many cases): - - `btcli subnets list`, `btcli subnets show`, `btcli subnets metagraph` - - The short forms `btcli s list`, `btcli s show`, `btcli subnet list`, and so on. - -The core difference is that *creating* or *altering* a subnet’s parameters requires a secure environment and a coldkey that has enough TAO and the appropriate on-chain privileges. - -## Governance Functions +## Requirements for `btcli` functions -Governance participants (senate members, sudo-level accounts) can propose changes, cast votes, or execute privileged commands that affect the entire network. They must have a **coldkey** with the relevant governance role (senate membership or sudo privileges). - -### Commands most relevant to governance: - -- **Senate / Proposals** (coldkey with senator role): - - `btcli sudo senate` - - `btcli sudo proposals` - - `btcli sudo senate-vote` - - `btcli sudo senate_vote` - - Aliases: `btcli su senate`, `btcli su proposals`, etc. -- **Sudo Commands** (coldkey with sudo privileges): - - `btcli sudo set`, `btcli sudo get` - - `btcli sudo set-take`, `btcli sudo get-take` - - `btcli sudo set_take`, `btcli sudo get_take` - - Aliases: `btcli su set`, `btcli su get`, etc. - -Because these commands can significantly change chain parameters or enact critical changes, they require a fully privileged coldkey in a **very** secure environment. - -## Requirements: +Different functions have different requirements. ### Coldkey Your primary, fully privileged key. Required for: @@ -143,7 +43,10 @@ Make sure your coldkey wallet has sufficient on-chain TAO to pay fees, stake, or ### Validator Permit An on-chain permission required for hotkeys that want to operate as validators. Without it, you can’t sign or submit weight commits. -## Workstation config + +## `btcli` commands and their permissions + +### `btcli config` - **Coldkey workstation**: Minimal exposure, ideally offline or with strong security controls. Used only for signing critical transactions (e.g., staking, governance, subnet creation). - **Hotkey workstation**: Online servers used for mining or validation. Contains only hotkeys. @@ -173,209 +76,221 @@ Permissionless - `btcli c metagraph`
-## Wallet management +### `btcli wallet` Mostly target a coldkey; should be performed on a secure CK workstation, NOT a mining workstation or any other insecure endpoint. HKs should be created on secure CK workstation and then carefully provisioned to less secure working nodes for mining and validation. +
+ `btcli wallet` +#### `btcli wallet list` +#### `btcli wallet swap-hotkey` +#### `btcli wallet regen-coldkey` +#### `btcli wallet regen-coldkeypub` +#### `btcli wallet regen-hotkey` +#### `btcli wallet new-hotkey` +#### `btcli wallet new-coldkey` +#### `btcli wallet create` +#### `btcli wallet balance` +#### `btcli wallet history` +#### `btcli wallet overview` +#### `btcli wallet transfer` +#### `btcli wallet inspect` +#### `btcli wallet faucet` +#### `btcli wallet set-identity` +#### `btcli wallet get-identity` +#### `btcli wallet sign` +#### `btcli wallet swap_hotkey` +#### `btcli wallet regen_coldkey` +#### `btcli wallet regen_coldkeypub` +#### `btcli wallet regen_hotkey` +#### `btcli wallet new_hotkey` +#### `btcli wallet new_coldkey` +#### `btcli wallet set_identity` +#### `btcli wallet get_identity` + +#### `btcli w list` +#### `btcli w swap-hotkey` +#### `btcli w regen-coldkey` +#### `btcli w regen-coldkeypub` +#### `btcli w regen-hotkey` +#### `btcli w new-hotkey` +#### `btcli w new-coldkey` +#### `btcli w create` +#### `btcli w balance` +#### `btcli w history` +#### `btcli w overview` +#### `btcli w transfer` +#### `btcli w inspect` +#### `btcli w faucet` +#### `btcli w set-identity` +#### `btcli w get-identity` +#### `btcli w sign` +#### `btcli w swap_hotkey` +#### `btcli w regen_coldkey` +#### `btcli w regen_coldkeypub` +#### `btcli w regen_hotkey` +#### `btcli w new_hotkey` +#### `btcli w new_coldkey` +#### `btcli w set_identity` +#### `btcli w get_identity` +#### `btcli wallets list` +#### `btcli wallets swap-hotkey` +#### `btcli wallets regen-coldkey` +#### `btcli wallets regen-coldkeypub` +#### `btcli wallets regen-hotkey` +#### `btcli wallets new-hotkey` +#### `btcli wallets new-coldkey` +#### `btcli wallets create` +#### `btcli wallets balance` +#### `btcli wallets history` +#### `btcli wallets overview` +#### `btcli wallets transfer` +#### `btcli wallets inspect` +#### `btcli wallets faucet` +#### `btcli wallets set-identity` +#### `btcli wallets get-identity` +#### `btcli wallets sign` +#### `btcli wallets swap_hotkey` +#### `btcli wallets regen_coldkey` +#### `btcli wallets regen_coldkeypub` +#### `btcli wallets regen_hotkey` +#### `btcli wallets new_hotkey` +#### `btcli wallets new_coldkey` +#### `btcli wallets set_identity` +#### `btcli wallets get_identity` +
-### `btcli wallet list` -### `btcli wallet swap-hotkey` -### `btcli wallet regen-coldkey` -### `btcli wallet regen-coldkeypub` -### `btcli wallet regen-hotkey` -### `btcli wallet new-hotkey` -### `btcli wallet new-coldkey` -### `btcli wallet create` -### `btcli wallet balance` -### `btcli wallet history` -### `btcli wallet overview` -### `btcli wallet transfer` -### `btcli wallet inspect` -### `btcli wallet faucet` -### `btcli wallet set-identity` -### `btcli wallet get-identity` -### `btcli wallet sign` -### `btcli wallet swap_hotkey` -### `btcli wallet regen_coldkey` -### `btcli wallet regen_coldkeypub` -### `btcli wallet regen_hotkey` -### `btcli wallet new_hotkey` -### `btcli wallet new_coldkey` -### `btcli wallet set_identity` -### `btcli wallet get_identity` - -### `btcli w list` -### `btcli w swap-hotkey` -### `btcli w regen-coldkey` -### `btcli w regen-coldkeypub` -### `btcli w regen-hotkey` -### `btcli w new-hotkey` -### `btcli w new-coldkey` -### `btcli w create` -### `btcli w balance` -### `btcli w history` -### `btcli w overview` -### `btcli w transfer` -### `btcli w inspect` -### `btcli w faucet` -### `btcli w set-identity` -### `btcli w get-identity` -### `btcli w sign` -### `btcli w swap_hotkey` -### `btcli w regen_coldkey` -### `btcli w regen_coldkeypub` -### `btcli w regen_hotkey` -### `btcli w new_hotkey` -### `btcli w new_coldkey` -### `btcli w set_identity` -### `btcli w get_identity` -### `btcli wallets list` -### `btcli wallets swap-hotkey` -### `btcli wallets regen-coldkey` -### `btcli wallets regen-coldkeypub` -### `btcli wallets regen-hotkey` -### `btcli wallets new-hotkey` -### `btcli wallets new-coldkey` -### `btcli wallets create` -### `btcli wallets balance` -### `btcli wallets history` -### `btcli wallets overview` -### `btcli wallets transfer` -### `btcli wallets inspect` -### `btcli wallets faucet` -### `btcli wallets set-identity` -### `btcli wallets get-identity` -### `btcli wallets sign` -### `btcli wallets swap_hotkey` -### `btcli wallets regen_coldkey` -### `btcli wallets regen_coldkeypub` -### `btcli wallets regen_hotkey` -### `btcli wallets new_hotkey` -### `btcli wallets new_coldkey` -### `btcli wallets set_identity` -### `btcli wallets get_identity` - -## Stake Management +### `stake` Coldkey w sufficient TAO or w stake for unstaking/moving Mostly target a coldkey; should be performed on a secure CK workstation, NOT a mining workstation or any other insecure endpoint. +
+ btcli stake +#### `btcli stake add` +#### `btcli stake remove` +#### `btcli stake list` +#### `btcli stake move` +#### `btcli stake transfer` +#### `btcli stake swap` +#### `btcli stake child` +##### `btcli stake child get` +##### `btcli stake child set` +##### `btcli stake child revoke` +##### `btcli stake child take` +#### `btcli stake children` +##### `btcli stake children get` +##### `btcli stake children set` +##### `btcli stake children revoke` +##### `btcli stake children take` +#### `btcli st add` +#### `btcli st remove` +#### `btcli st list` +#### `btcli st move` +#### `btcli st transfer` +#### `btcli st swap` +#### `btcli st child` +##### `btcli st child get` +##### `btcli st child set` +##### `btcli st child revoke` +##### `btcli st child take` +#### `btcli st children` +##### `btcli st children get` +##### `btcli st children set` +##### `btcli st children revoke` +##### `btcli st children take` +
+ +### `btcli sudo` -### `btcli stake add` -### `btcli stake remove` -### `btcli stake list` -### `btcli stake move` -### `btcli stake transfer` -### `btcli stake swap` -### `btcli stake child` -#### `btcli stake child get` -#### `btcli stake child set` -#### `btcli stake child revoke` -#### `btcli stake child take` -### `btcli stake children` -#### `btcli stake children get` -#### `btcli stake children set` -#### `btcli stake children revoke` -#### `btcli stake children take` -### `btcli st add` -### `btcli st remove` -### `btcli st list` -### `btcli st move` -### `btcli st transfer` -### `btcli st swap` -### `btcli st child` -#### `btcli st child get` -#### `btcli st child set` -#### `btcli st child revoke` -#### `btcli st child take` -### `btcli st children` -#### `btcli st children get` -#### `btcli st children set` -#### `btcli st children revoke` -#### `btcli st children take` - - -## Subnet Management and Governance - -Complicated! - -Subnet management: Setters need CK with creator permissions, getters are typically permissionless (for listing or reading). Creating or modifying subnets (burn cost, price, hyperparameters) requires a coldkey with sufficient balance and permissions. - -Senate stuff: CK with senator role for proposals and votes, or CK with sudo privileges for certain chain-level commands. + +CK with senator role for proposals and votes, or CK with sudo privileges for certain chain-level commands. miner/validator registration stuff: typically uses a hotkey for the registration extrinsic, though the creation of subnets (which set registration parameters) requires a coldkey. -### `btcli sudo set` -### `btcli sudo get` -### `btcli sudo senate` -### `btcli sudo proposals` -### `btcli sudo senate-vote` -### `btcli sudo set-take` -### `btcli sudo get-take` -### `btcli sudo senate_vote` -### `btcli sudo get_take` -### `btcli sudo set_take` -### `btcli su set` -### `btcli su get` - -### `btcli su senate` -### `btcli su proposals` -### `btcli su senate-vote` -### `btcli su set-take` -### `btcli su get-take` -### `btcli su senate_vote` -### `btcli su get_take` -### `btcli su set_take` - -### `btcli subnets hyperparameters` -### `btcli subnets list` -### `btcli subnets burn-cost` -### `btcli subnets create` -### `btcli subnets pow-register` -### `btcli subnets register` -### `btcli subnets metagraph` -### `btcli subnets show` -### `btcli subnets price` -### `btcli subnets burn_cost` -### `btcli subnets pow_register` -### `btcli s hyperparameters` -### `btcli s list` -### `btcli s burn-cost` -### `btcli s create` -### `btcli s pow-register` -### `btcli s register` -### `btcli s metagraph` -### `btcli s show` -### `btcli s price` -### `btcli s burn_cost` -### `btcli s pow_register` -### `btcli subnet hyperparameters` -### `btcli subnet list` -### `btcli subnet burn-cost` -### `btcli subnet create` -### `btcli subnet pow-register` -### `btcli subnet register` -### `btcli subnet metagraph` -### `btcli subnet show` -### `btcli subnet price` -### `btcli subnet burn_cost` -### `btcli subnet pow_register` -### `btcli weights reveal` -### `btcli weights commit` - - -## Weights +Validator take... -Setters require an active hotkey that has a validator permit. Reading or querying weights is generally permissionless, but committing or revealing them is only for registered validators. +
+ `btcli sudo` +#### `btcli sudo set` +#### `btcli sudo get` +#### `btcli sudo senate` +#### `btcli sudo proposals` +#### `btcli sudo senate-vote` +#### `btcli sudo set-take` +#### `btcli sudo get-take` +#### `btcli sudo senate_vote` +#### `btcli sudo get_take` +#### `btcli sudo set_take` +#### `btcli su set` +#### `btcli su get` + +#### `btcli su senate` +#### `btcli su proposals` +#### `btcli su senate-vote` +#### `btcli su set-take` +#### `btcli su get-take` +#### `btcli su senate_vote` +#### `btcli su get_take` +#### `btcli su set_take` +
+### `btcli subnets` + +Setters need CK with creator permissions, getters are typically permissionless (for listing or reading). Creating or modifying subnets (burn cost, price, hyperparameters) requires a coldkey with sufficient balance and permissions. -### `btcli wt reveal` -### `btcli wt commit` -### `btcli weight reveal` -### `btcli weight commit` +
+ `btcli subnets` +#### `btcli subnets hyperparameters` +#### `btcli subnets list` +#### `btcli subnets burn-cost` +#### `btcli subnets create` +#### `btcli subnets pow-register` +#### `btcli subnets register` +#### `btcli subnets metagraph` +#### `btcli subnets show` +#### `btcli subnets price` +#### `btcli subnets burn_cost` +#### `btcli subnets pow_register` +#### `btcli s hyperparameters` +#### `btcli s list` +#### `btcli s burn-cost` +#### `btcli s create` +#### `btcli s pow-register` +#### `btcli s register` +#### `btcli s metagraph` +#### `btcli s show` +#### `btcli s price` +#### `btcli s burn_cost` +#### `btcli s pow_register` +#### `btcli subnet hyperparameters` +#### `btcli subnet list` +#### `btcli subnet burn-cost` +#### `btcli subnet create` +#### `btcli subnet pow-register` +#### `btcli subnet register` +#### `btcli subnet metagraph` +#### `btcli subnet show` +#### `btcli subnet price` +#### `btcli subnet burn_cost` +#### `btcli subnet pow_register` +
+### Weights + +Setters require an active hotkey that has a validator permit. Reading or querying weights is generally permissionless, but committing or revealing them is only for registered validators. +
+ `btcli weight` +#### `btcli weights reveal` +#### `btcli weights commit` + +#### `btcli wt reveal` +#### `btcli wt commit` +#### `btcli weight reveal` +#### `btcli weight commit` +
-## Utils ??? +### Utils ??? -### `btcli utils convert` +#### `btcli utils convert` This is a convenience command for performing conversions between minimal units (RAO) and TAO, or other chain-specific conversions. Permissionless (no key required) because it performs no on-chain operation, just a local calculation. diff --git a/docs/governance/senators-btcli-guide.md b/docs/governance/senators-btcli-guide.md new file mode 100644 index 00000000..7c7551a7 --- /dev/null +++ b/docs/governance/senators-btcli-guide.md @@ -0,0 +1,32 @@ +--- +title: "Senator's Guide to `BTCLI`" +--- + +# Senator's Guide to `BTCLI` + +Governance participants (senate members, sudo-level accounts) can propose changes, cast votes, or execute privileged commands that affect the entire network. They must have a **coldkey** with the relevant governance role (senate membership or sudo privileges). + +**Senate requirements:** In order to participate in the Senate, a coldkey must: + +- Have registered with any subnetwork as a hotkey-coldkey pair. +- Have nominated themselves as a delegate for anyone to stake their $TAO with. +- Have a hotkey stake value is greater than 2% of the network's total stake amount, through delegation or self-stake. +- Have elected to participate in the Senate. + +See: [Senate](../senate). + +**Commands most relevant to governance:** + +- **Senate / Proposals** (coldkey with senator role): + - `btcli sudo senate` + - `btcli sudo proposals` + - `btcli sudo senate-vote` + - `btcli sudo senate_vote` + - Aliases: `btcli su senate`, `btcli su proposals`, etc. +- **Sudo Commands** (coldkey with sudo privileges): + - `btcli sudo set`, `btcli sudo get` + - `btcli sudo set-take`, `btcli sudo get-take` + - `btcli sudo set_take`, `btcli sudo get_take` + - Aliases: `btcli su set`, `btcli su get`, etc. + +Because these commands can significantly change chain parameters or enact critical changes, they require a fully privileged coldkey in a **very** secure environment. diff --git a/docs/miners/miners-btcli-guide.md b/docs/miners/miners-btcli-guide.md new file mode 100644 index 00000000..e0c5192a --- /dev/null +++ b/docs/miners/miners-btcli-guide.md @@ -0,0 +1,26 @@ +--- +title: "Miner's Guide to `BTCLI`" +--- + +# Miner's Guide to `BTCLI` + +Miners run processes that serve or forward inference requests on the network. They register with the chain using a **hotkey** to obtain a UID for the subnet(s) in which they operate. In addition, they must use a coldkey to manage their TAO and any alpha currencies, essentially perforoming all the functions of stakers. + +This page discusses btcli stuff specifically for Miners. For general coverage of BTCLI and permissions stuff, see: [Bittensor CLI: Permissions Guide](../btcli-permissions) + +Hotkeys and coldkeys are different yada yada... + +Miners primarily rely on **hotkeys** for daily operations. The **coldkey** is only needed when you need to create or fund that hotkey, or if you want to stake additional TAO or pay the burn for certain registrations. + +Hotkey creation can be done on a secure machine (paired with your coldkey). **However, day-to-day mining** is done with the hotkey in a less secure environment (the “mining rig” or server), since it needs to be online to serve inference requests. + +Coldkey operations should be performed in a secure environments... + +**Additional Commands most relevant to miners:** + +- **Hotkey management**: +- `btcli wallet new-hotkey` / `btcli wallet regen-hotkey`: Creation/regeneration of hotkeys. Typically do these on a secure machine (paired to your coldkey), then transfer the hotkey file or mnemonic to the mining machine. +- `btcli wallet balance` and `btcli wallet overview`: Might be used to check the hotkey’s on-chain state or small balances. (Hotkey on a less secure machine is lower risk, but still treat it with caution.) + +_ **Subnet registration**: +- `btcli subnets pow-register`, `btcli subnets pow_register`, `btcli subnets register`: Miner uses these to register themselves on the subnet, typically from a machine with the hotkey. **However,** the associated transaction cost must come from the coldkey. So you either sign it with your coldkey (secure environment) or set up a valid signature flow. The **registration** associates the hotkey with a miner UID on the subnet. diff --git a/docs/staking-and-delegation/stakers-btcli-guide.md b/docs/staking-and-delegation/stakers-btcli-guide.md new file mode 100644 index 00000000..ebff3df4 --- /dev/null +++ b/docs/staking-and-delegation/stakers-btcli-guide.md @@ -0,0 +1,35 @@ +--- +title: "Staker's Guide to `BTCLI`" +--- + +# Staker's Guide to `BTCLI` + +Stakers enter value into the Bittensor network by acquiring TAO and staking or *delegating* it to validators to support their work. As validators extract emissions, a certain percentage goes back to stakers. + +See [Staking/Delegation Overview](./delegation.md). + +Stakers must be familiar with operations related to managing the TAO and staked alpha tokens in their Bittensor wallet balance. + +Performing these functions requires using a **coldkey**, and hence must be performed in a **highly secure environment** for any wallet connected to real (mainnet) TAO balance. A leak of your coldkey can lead to a catastrophic loss of funds. + +Accounts can be viewed without using a coldkey, but any changes to stake, transfers, or delegations require signing with the coldkey. + +**Commands most relevant to stakers:** +- **Wallet Commands** (Coldkey required for modifications): + - `btcli wallet create`, `btcli wallet new-coldkey`, `btcli wallet new_coldkey`: Create or generate a new coldkey (secure environment). + - `btcli wallet balance`, `btcli wallet overview`, `btcli wallet history`: View balances and transaction history. Viewing does not require a coldkey *if* you only query public chain state, but typically you’ll specify the coldkey to reference your own account data. + - `btcli wallet transfer`: Transfer TAO from your coldkey to another address. Requires a coldkey signature (secure environment). + - `btcli wallet faucet`: (Testnet only or any environment with a faucet). Coldkey not necessarily required if the faucet only needs a public key, but typically you’ll manage it via your wallet. + - `btcli wallet inspect`: Inspect wallet details (permissionless unless you want to do private key operations). +- **Stake Management** (All require **coldkey** in a secure environment): + - `btcli stake add`, `btcli stake remove`, `btcli stake list`, `btcli stake move`, `btcli stake transfer`, `btcli stake swap` + - `btcli stake child ...` / `btcli stake children ...` (get, set, revoke, take) + - Short aliases: `btcli st add`, `btcli st remove`, etc. +- **Subnet Discovery**: + - `btcli subnets list`, `btcli subnets show`, `btcli subnets metagraph`: Permissionless *reads* to see available subnets or node info. + - `btcli subnets price`, `btcli subnets burn-cost`, `btcli subnets burn_cost`: Show the required burn to register in a particular subnet. Permissionless read. +- **Config**: + - `btcli config set`, `btcli config get`, etc. (Permissionless) to configure a `btcli` environment. + +In summary, **stakers only need a coldkey**. Staking commands should **never** be run on an insecure or public-facing machine since the coldkey manages your TAO holdings. + diff --git a/docs/subnets/subnet-creators-btcli-guide.md b/docs/subnets/subnet-creators-btcli-guide.md new file mode 100644 index 00000000..bce0cd13 --- /dev/null +++ b/docs/subnets/subnet-creators-btcli-guide.md @@ -0,0 +1,28 @@ +--- +title: "Subnet Creator's Guide to `BTCLI`" +--- + +# Subnet Creator's Guide to `BTCLI` + +Subnet creators define and manage new subnets, specifying parameters like burn cost, hyperparameters, or other chain-level configurations. This role inherently requires a **coldkey** with sufficient balance/permissions to create or update subnets. + +This page discusses btcli stuff specifically for Subnet Creators. For general coverage of BTCLI and permissions stuff, see: [Bittensor CLI: Permissions Guide](../btcli-permissions.md) + + +**Subnet Creator Requirements:** +- to create a new subnet +- to sudo on your own subnet + +**Commands most relevant to subnet creators:** +- **Subnet Creation / Configuration** (all require **coldkey** in a secure environment to sign on-chain transactions): + - `btcli subnets create` + - `btcli subnets hyperparameters` + - `btcli subnets burn-cost` / `btcli subnets burn_cost` + - `btcli subnets price` + - `btcli subnets set` (some advanced usage might come in via `sudo` or governance commands) + - Similarly, short forms like `btcli s create`, `btcli s burn-cost`, `btcli subnet create`, etc. +- **Reads** (permissionless in many cases): + - `btcli subnets list`, `btcli subnets show`, `btcli subnets metagraph` + - The short forms `btcli s list`, `btcli s show`, `btcli subnet list`, and so on. + +The core difference is that *creating* or *altering* a subnet’s parameters requires a secure environment and a coldkey that has enough TAO and the appropriate on-chain privileges. \ No newline at end of file diff --git a/docs/validators/validators-btcli-guide.md b/docs/validators/validators-btcli-guide.md new file mode 100644 index 00000000..c1b1c2d7 --- /dev/null +++ b/docs/validators/validators-btcli-guide.md @@ -0,0 +1,45 @@ +--- +title: "Validator's Guide to `BTCLI`" +--- + +# Validator's Guide to `BTCLI` + +Validators evaluate miner performance, and post their evaluations to the blockchain. + +This page discusses btcli stuff specifically for Validators. For general coverage of BTCLI and permissions stuff, see: [Bittensor CLI: Permissions Guide](../btcli-permissions) + +- **Hotkey**: + + Used to set weights + +- **Coldkey** is needed for any stake management or large fund transfers. + +- **Weight-setting requirements**: + +To have a **validator permit** in a given subnet, allowing you to submit miner evaluations using the [`set_weights`](pathname:///python-api/html/autoapi/bittensor/core/extrinsics/set_weights/index.html) function, you must meet the following requirements: + + - Your hotkey must be registered, granting you a UID on the subnet + - You must have a stake-weight on the subnet of least 1000, including stake delegated to your hotkey from other wallets' coldkeys. A validator's stake weight in a subnet equals their alpha stake plus their TAO stake times the `tao_weight` parameter (current value: 0.18): + + $$ + + \text{Validator stake weight} = \alpha + 0.18 \times \tau + + $$ + - You must be one of the top 64 validators in the subnet, ranked by stake. + + +**Commands most relevant to validators:** +- **Weights**: + - `btcli weights reveal`, `btcli weights commit` + - `btcli wt reveal`, `btcli wt commit` + - `btcli weight reveal`, `btcli weight commit` + These require a hotkey with an active validator permit on the subnet. Typically run in a live environment (the validator node). + +- **Stake Management** (if you stake TAO to your validator hotkey or accept delegations): + - `btcli stake add`, `btcli stake remove`, `btcli stake move`, etc. + Requires the coldkey in a **secure environment** if you are adding or removing stake from your own coldkey to your validator hotkey. +- **Subnet Registration**: + - If you are validating on a particular subnet, you often must register with `btcli subnets register` or `btcli subnets pow-register`, same as miners. This also typically involves your coldkey to pay any required fees, while awarding your hotkey the validator status/UID in that subnet. + +In short, validators use their **hotkey** for daily validation and weights. The coldkey is still needed for any staking or managing TAO, so you keep it offline or in a more secure environment whenever possible. diff --git a/sidebars.js b/sidebars.js index e2144567..c92f9926 100644 --- a/sidebars.js +++ b/sidebars.js @@ -59,6 +59,7 @@ const sidebars = { link: {type: "doc", id: "staking-and-delegation/delegation",}, items: [ "staking-and-delegation/delegation", + "staking-and-delegation/stakers-btcli-guide", "dynamic-tao/staking-unstaking-dtao", "staking-and-delegation/managing-stake-btcli", "staking-and-delegation/managing-stake-sdk", @@ -73,6 +74,7 @@ const sidebars = { link: {type: "doc", id: "miners/index",}, items: [ "miners/index", + "miners/miners-btcli-guide" ], }, @@ -84,7 +86,8 @@ const sidebars = { link: {type: "doc", id: "validators/index",}, items: [ "validators/index", - "subnets/child-hotkeys", + "subnets/child-hotkeys", + "validators/validators-btcli-guide" ], }, { @@ -94,6 +97,7 @@ const sidebars = { collapsed: true, items: [ "subnets/create-a-subnet", + "subnets/subnet-creators-btcli-guide", "subnets/subnet-hyperparameters", "subnets/working-with-subnets", "subnets/walkthrough-prompting", @@ -196,6 +200,7 @@ const sidebars = { items: [ "governance", "senate", + "governance/senators-btcli-guide" ], }, { From 5ea9761daa2c00c6f6f618782b36588dbc0a404f Mon Sep 17 00:00:00 2001 From: Michael Trestman Date: Mon, 3 Mar 2025 22:16:35 -0800 Subject: [PATCH 13/23] wip --- docs/governance/senators-btcli-guide.md | 2 ++ docs/staking-and-delegation/stakers-btcli-guide.md | 4 +++- 2 files changed, 5 insertions(+), 1 deletion(-) diff --git a/docs/governance/senators-btcli-guide.md b/docs/governance/senators-btcli-guide.md index 7c7551a7..1aab1ab0 100644 --- a/docs/governance/senators-btcli-guide.md +++ b/docs/governance/senators-btcli-guide.md @@ -6,6 +6,8 @@ title: "Senator's Guide to `BTCLI`" Governance participants (senate members, sudo-level accounts) can propose changes, cast votes, or execute privileged commands that affect the entire network. They must have a **coldkey** with the relevant governance role (senate membership or sudo privileges). +This page discusses btcli stuff specifically for Senators. For general coverage of BTCLI and permissions stuff, see: [Bittensor CLI: Permissions Guide](../btcli-permissions) + **Senate requirements:** In order to participate in the Senate, a coldkey must: - Have registered with any subnetwork as a hotkey-coldkey pair. diff --git a/docs/staking-and-delegation/stakers-btcli-guide.md b/docs/staking-and-delegation/stakers-btcli-guide.md index ebff3df4..0ece3133 100644 --- a/docs/staking-and-delegation/stakers-btcli-guide.md +++ b/docs/staking-and-delegation/stakers-btcli-guide.md @@ -6,7 +6,9 @@ title: "Staker's Guide to `BTCLI`" Stakers enter value into the Bittensor network by acquiring TAO and staking or *delegating* it to validators to support their work. As validators extract emissions, a certain percentage goes back to stakers. -See [Staking/Delegation Overview](./delegation.md). +See also: +- [Staking/Delegation Overview](./delegation.md) +- [Bittensor CLI: Permissions Guide](../btcli-permissions) Stakers must be familiar with operations related to managing the TAO and staked alpha tokens in their Bittensor wallet balance. From 872715208c8387d1d1876354d09b745710b3f1c0 Mon Sep 17 00:00:00 2001 From: Michael Trestman Date: Tue, 4 Mar 2025 08:57:26 -0800 Subject: [PATCH 14/23] wip --- docs/btcli-permissions.md | 69 +++++++++++++++++++++++++++++++-------- docs/validators/index.md | 8 ++++- 2 files changed, 62 insertions(+), 15 deletions(-) diff --git a/docs/btcli-permissions.md b/docs/btcli-permissions.md index 5f5af7af..45e3a187 100644 --- a/docs/btcli-permissions.md +++ b/docs/btcli-permissions.md @@ -15,9 +15,10 @@ See also the `btcli` permissions guides for specific Bittensor personas: - [Senator's Guide to `BTCLI`](./governance/senators-btcli-guide) -:::info -For additional background on the difference between **coldkeys** and **hotkeys**, please refer to the [Wallets, Coldkeys and Hotkeys in Bittensor](#wallets-coldkeys-and-hotkeys-in-bittensor-reference) section below (summarized from [the separate doc](./working-with-keys.md)). -::: +Other resources: + +- [Wallets, Coldkeys and Hotkeys in Bittensor](./wallets) + ## Requirements for `btcli` functions @@ -38,17 +39,57 @@ Used for daily operations with lower privileges: Usually stored on a less secure environment than the coldkey because it must be online and accessible for repeated use. ### Available liquidity -Make sure your coldkey wallet has sufficient on-chain TAO to pay fees, stake, or register subnets. Insufficient balance will cause transactions to fail. + +Make sure your coldkey wallet has sufficient on-chain TAO to pay fees, stake, or register subnets. + +- POW vs POS reg +- Subnet reg +- ??? + +Operations to unstake alpha into TAO, and move or transfer stake, have minimum liquidity requirements ( is this flat or subnet configured or what ???). + ### Validator Permit -An on-chain permission required for hotkeys that want to operate as validators. Without it, you can’t sign or submit weight commits. +To set weights as a validator in a subnet, you must have a stake-weight on the subnet of least 1000, including stake delegated to your hotkey from other wallets' coldkeys. A validator's stake weight in a subnet equals their alpha stake plus their TAO stake times the `tao_weight` parameter (current value: 0.18): + + $$ + + \text{Validator stake weight} = \alpha + 0.18 \times \tau + + $$ + + +### Senate requirements + +In order to participate in the Senate, a coldkey must: + +- Have registered with any subnetwork as a hotkey-coldkey pair. +- Have nominated themselves as a delegate for anyone to stake their $TAO with. +- Have a hotkey stake value is greater than 2% of the network's total stake amount, through delegation or self-stake. +- Have elected to participate in the Senate. + +## `btcli` commands + +### `config` + +The `btcli config ...` commands are used to configure `btcli`, including: +- selecting the targeted network (`finney` a.k.a. mainnet or `test` for test network) +- setting the directory where your Bittensor wallet coldkeys and/or hotkeys are stored + +These commands don't require any permissions to run, but you'll run these commands on all `btcli` workstations: + +- **Permissionless workstation**: You don't need a key to view subnets and stuff. You do need a coldkey apparently for `btcli view dashboard`, but it can be a throwaway key, it doesn't need any TAO or anything else attached to it. +- **Coldkey workstation**: Contains coldkey in the `wallet_path`. For any coldkey associated with mainnet TAO, this should only be done on a secure workstation. -## `btcli` commands and their permissions + :::tip coldkey workstation security + ... + ::: -### `btcli config` -- **Coldkey workstation**: Minimal exposure, ideally offline or with strong security controls. Used only for signing critical transactions (e.g., staking, governance, subnet creation). -- **Hotkey workstation**: Online servers used for mining or validation. Contains only hotkeys. +- **Hotkey workstation**: Can include servers used for mining or validation. Contains only hotkeys in the `wallet_path` in the `btcli config`. Compromised hotkeys can damage your reputation if they are used to maliciously submit false weights (if you are a validator), or register and submit crappy work ??? if you are a miner, which can be costly. However, ownership of TAO or alpha stake can only be transferred with a coldkey. + :::tip hotkey workstation security + ... + :::
btcli config @@ -76,7 +117,7 @@ Permissionless - `btcli c metagraph`
-### `btcli wallet` +### `wallet` Mostly target a coldkey; should be performed on a secure CK workstation, NOT a mining workstation or any other insecure endpoint. @@ -202,7 +243,7 @@ Mostly target a coldkey; should be performed on a secure CK workstation, NOT a m ##### `btcli st children take`
-### `btcli sudo` +### `sudo` CK with senator role for proposals and votes, or CK with sudo privileges for certain chain-level commands. @@ -235,7 +276,7 @@ Validator take... #### `btcli su get_take` #### `btcli su set_take` -### `btcli subnets` +### `subnets` Setters need CK with creator permissions, getters are typically permissionless (for listing or reading). Creating or modifying subnets (burn cost, price, hyperparameters) requires a coldkey with sufficient balance and permissions. @@ -276,7 +317,7 @@ Setters need CK with creator permissions, getters are typically permissionless ( #### `btcli subnet pow_register` -### Weights +### `weights` Setters require an active hotkey that has a validator permit. Reading or querying weights is generally permissionless, but committing or revealing them is only for registered validators.
@@ -290,7 +331,7 @@ Setters require an active hotkey that has a validator permit. Reading or queryin #### `btcli weight commit`
-### Utils ??? +### `utils` #### `btcli utils convert` This is a convenience command for performing conversions between minimal units (RAO) and TAO, or other chain-specific conversions. Permissionless (no key required) because it performs no on-chain operation, just a local calculation. diff --git a/docs/validators/index.md b/docs/validators/index.md index 70449486..c37cc8cb 100644 --- a/docs/validators/index.md +++ b/docs/validators/index.md @@ -24,7 +24,13 @@ Validating is not supported on Windows. To have a **validator permit** in a given subnet, allowing you to submit miner evaluations using the [`set_weights`](pathname:///python-api/html/autoapi/bittensor/core/extrinsics/set_weights/index.html) function, you must meet the following requirements: - Your hotkey must be registered, granting you a UID on the subnet -- You must at least 1000 TAO staked to your hotkey +- You must have a stake-weight on the subnet of least 1000, including stake delegated to your hotkey from other wallets' coldkeys. A validator's stake weight in a subnet equals their alpha stake plus their TAO stake times the `tao_weight` parameter (current value: 0.18): + + $$ + + \text{Validator stake weight} = \alpha + 0.18 \times \tau + + $$ - You must be one of the top 64 validators in the subnet, ranked by stake. ## Validator registration From ab7275535812d1c6437a83ff3059fc16b945c503 Mon Sep 17 00:00:00 2001 From: Michael Trestman Date: Tue, 4 Mar 2025 09:02:05 -0800 Subject: [PATCH 15/23] wip --- docs/btcli-permissions.md | 19 ++++++++++++------- 1 file changed, 12 insertions(+), 7 deletions(-) diff --git a/docs/btcli-permissions.md b/docs/btcli-permissions.md index 45e3a187..0bef09b5 100644 --- a/docs/btcli-permissions.md +++ b/docs/btcli-permissions.md @@ -25,18 +25,23 @@ Other resources: Different functions have different requirements. ### Coldkey -Your primary, fully privileged key. Required for: +Your primary, fully privileged key. Must be used on a secure **coldkey workstation** to avoid catastrophic loss or malicious actions if compromised. + +Required for: - Managing stake (add/remove/move). - Moving or transferring TAO (i.e., `wallet transfer`). - Creating or modifying subnets (`btcli subnets create`). - Voting or proposing in governance. -Must be used on a **high-security machine** to avoid catastrophic loss if compromised. + ### Hotkey -Used for daily operations with lower privileges: -- Running miners (signing inference, staying online). -- Running validators (weight commits, daily on-chain actions). -Usually stored on a less secure environment than the coldkey because it must be online and accessible for repeated use. +Used for daily operations with lower privileges. Usually stored on a less secure environment than the coldkey because it must be online and accessible for repeated use. + +- Running miners: serving requests from validators +- Running validators: + - making requests to miners weight + - setting weights + ### Available liquidity @@ -48,8 +53,8 @@ Make sure your coldkey wallet has sufficient on-chain TAO to pay fees, stake, or Operations to unstake alpha into TAO, and move or transfer stake, have minimum liquidity requirements ( is this flat or subnet configured or what ???). - ### Validator Permit + To set weights as a validator in a subnet, you must have a stake-weight on the subnet of least 1000, including stake delegated to your hotkey from other wallets' coldkeys. A validator's stake weight in a subnet equals their alpha stake plus their TAO stake times the `tao_weight` parameter (current value: 0.18): $$ From 3bdcfc76f932f29da1eb02d8dfc43148f2a9d17a Mon Sep 17 00:00:00 2001 From: Michael Trestman Date: Tue, 4 Mar 2025 09:05:56 -0800 Subject: [PATCH 16/23] wip --- docs/btcli-permissions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/btcli-permissions.md b/docs/btcli-permissions.md index 0bef09b5..625be2a3 100644 --- a/docs/btcli-permissions.md +++ b/docs/btcli-permissions.md @@ -17,7 +17,7 @@ See also the `btcli` permissions guides for specific Bittensor personas: Other resources: -- [Wallets, Coldkeys and Hotkeys in Bittensor](./wallets) +- [Wallets, Coldkeys and Hotkeys in Bittensor](./getting-started/wallets) ## Requirements for `btcli` functions From 47b15807e7d8ce909131496ea64ae3b22a0e8213 Mon Sep 17 00:00:00 2001 From: Michael Trestman Date: Tue, 4 Mar 2025 09:09:58 -0800 Subject: [PATCH 17/23] wip --- docs/btcli.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/btcli.md b/docs/btcli.md index d5f7edc9..38ae1815 100644 --- a/docs/btcli.md +++ b/docs/btcli.md @@ -3475,7 +3475,7 @@ btcli stake [OPTIONS] COMMAND [ARGS]... Stake TAO to one or more hotkeys on specific netuids with your coldkey. -Stake is always added through your coldkey's free balance. For stake movement, please see the `btcli stake move` command. +Stake is always added through your coldkey's free balance. For stake movement, see the `btcli stake move` command. Common Examples: 1. Interactive staking (guided prompts): @@ -4147,7 +4147,7 @@ btcli st [OPTIONS] COMMAND [ARGS]... Stake TAO to one or more hotkeys on specific netuids with your coldkey. -Stake is always added through your coldkey's free balance. For stake movement, please see +Stake is always added through your coldkey's free balance. For stake movement, see the `btcli stake move` command. From 805ad9f07c0549020c22c0408a95747c190c1a70 Mon Sep 17 00:00:00 2001 From: Michael Trestman Date: Tue, 4 Mar 2025 10:27:54 -0800 Subject: [PATCH 18/23] wip --- docs/btcli-permissions.md | 4 ++++ docs/subnets/subnet-creators-btcli-guide.md | 2 +- docs/validators/validators-btcli-guide.md | 6 ++++-- sidebars.js | 1 + 4 files changed, 10 insertions(+), 3 deletions(-) diff --git a/docs/btcli-permissions.md b/docs/btcli-permissions.md index 625be2a3..aeb39bbf 100644 --- a/docs/btcli-permissions.md +++ b/docs/btcli-permissions.md @@ -73,6 +73,10 @@ In order to participate in the Senate, a coldkey must: - Have a hotkey stake value is greater than 2% of the network's total stake amount, through delegation or self-stake. - Have elected to participate in the Senate. + + + + ## `btcli` commands ### `config` diff --git a/docs/subnets/subnet-creators-btcli-guide.md b/docs/subnets/subnet-creators-btcli-guide.md index bce0cd13..bdb2eec3 100644 --- a/docs/subnets/subnet-creators-btcli-guide.md +++ b/docs/subnets/subnet-creators-btcli-guide.md @@ -6,7 +6,7 @@ title: "Subnet Creator's Guide to `BTCLI`" Subnet creators define and manage new subnets, specifying parameters like burn cost, hyperparameters, or other chain-level configurations. This role inherently requires a **coldkey** with sufficient balance/permissions to create or update subnets. -This page discusses btcli stuff specifically for Subnet Creators. For general coverage of BTCLI and permissions stuff, see: [Bittensor CLI: Permissions Guide](../btcli-permissions.md) +This page discusses btcli stuff specifically for Subnet Creators. For general coverage of BTCLI and permissions stuff, see: [Bittensor CLI: Permissions Guide](../btcli-permissions) **Subnet Creator Requirements:** diff --git a/docs/validators/validators-btcli-guide.md b/docs/validators/validators-btcli-guide.md index c1b1c2d7..d261457c 100644 --- a/docs/validators/validators-btcli-guide.md +++ b/docs/validators/validators-btcli-guide.md @@ -8,12 +8,14 @@ Validators evaluate miner performance, and post their evaluations to the blockch This page discusses btcli stuff specifically for Validators. For general coverage of BTCLI and permissions stuff, see: [Bittensor CLI: Permissions Guide](../btcli-permissions) +## Requirements + +- **Coldkey** is needed for any stake management or large fund transfers. + - **Hotkey**: Used to set weights -- **Coldkey** is needed for any stake management or large fund transfers. - - **Weight-setting requirements**: To have a **validator permit** in a given subnet, allowing you to submit miner evaluations using the [`set_weights`](pathname:///python-api/html/autoapi/bittensor/core/extrinsics/set_weights/index.html) function, you must meet the following requirements: diff --git a/sidebars.js b/sidebars.js index c92f9926..ddea408c 100644 --- a/sidebars.js +++ b/sidebars.js @@ -139,6 +139,7 @@ const sidebars = { items: [ "getting-started/wallets", "working-with-keys", + "getting-started/coldkey-hotkey-security" ] }, { From e20aea2477af90a851eec8f0a8babf9182e5174c Mon Sep 17 00:00:00 2001 From: Michael Trestman Date: Tue, 4 Mar 2025 10:32:13 -0800 Subject: [PATCH 19/23] wip --- .../coldkey-hotkey-security.md | 139 ++++++++++++++++++ 1 file changed, 139 insertions(+) create mode 100644 docs/getting-started/coldkey-hotkey-security.md diff --git a/docs/getting-started/coldkey-hotkey-security.md b/docs/getting-started/coldkey-hotkey-security.md new file mode 100644 index 00000000..93b7646a --- /dev/null +++ b/docs/getting-started/coldkey-hotkey-security.md @@ -0,0 +1,139 @@ +--- +title: "Coldkey and Hotkey Workstation Security" +--- + +# Coldkey and Hotkey Workstation Security + +This page goes into detail of security concerns for working with coldkeys and hotkeys in Bittensor. + +See also: + +- [Intro: Wallets, Coldkeys and Hotkeys in Bittensor](./wallets) +- [Bittensor CLI: Permissions Guide](../btcli-permissions) + +## Coldkey workstation security + +Treat your coldkey as the ultimate authority over your Bittensor wallet. A compromised coldkey allows an attacker holder to transfer (steal) your TAO, redelegate your stakes, or take other actions that can’t be reversed. Because of these high stakes, many best practices from both cryptocurrency storage and modern DevOps/MLOps environments apply here. Prioritize confidentiality and integrity over convenience when handling a coldkey. + +### Isolation of coldkey operations + +The first principle is to isolate coldkey operations from day-to-day or internet-exposed systems. This often means using a dedicated, air-gapped machine or at least a workstation that is minimally connected to the internet, and has only highly trusted software installed to minimize the risk of malware or keyloggers intercepting your coldkey or recovery seed phrase. + +### Coldkeys do not mine + +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. + +### Air-gapped machines + +Is it possible to transfer an unsigned extrinsic to a USB key, plug that into your coldkey workstation, sign offline, then move the signed payload back to an online machine to broadcast it ??? + +### Minimal operating system + +What is a minimal (?) recommended operating system for a bittensor coldkey workstation ??? + +### Hardware Security Modules (HSMs) and Hardware Wallets + +Ledger... + +dtao enabled? + +single use cell phone? + + +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? + + +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 + +For more on hardware wallets and HSMs, see: +- [Ledger’s official security overview](https://www.ledger.com/academy/securely-manage-your-crypto) +- [AWS CloudHSM documentation](https://aws.amazon.com/cloudhsm/) +- oblique reference to [HashiCorp Vault with HSM integration](https://developer.hashicorp.com/vault/docs/configuration/seal) + +### Strong Encryption of Coldkey Files + +how does encryption work in btcli? should you add your own encryption? +full-disk encryption (FDE) to protect keys if the physical machine is stolen. eg,veracrypt, LUKS on Linux or BitLocker on Windows... + +### Operational Hygiene +Even on a minimal or air-gapped machine, follow standard security hygiene: +- **Use strong passwords** for your encryption passphrases. +- **Never reuse credentials** across different environments. +- Keep your workstation’s firmware (UEFI/BIOS) and OS updated. +- Maintain logs and check for unusual activity or tampering. +- Disable all network services (SSH, RDP, or anything else) if you don’t strictly need them. + +### Secure Key Backups + +You must keep redundant backups of your coldkey, but those backups must be just as secure as the primary. Common approaches: +- **Paper backups** of the mnemonic phrase, sealed in tamper-evident envelopes, stored in multiple physically secure locations. +- **Encrypted USB drives** (with strong passphrases) stored in a safety deposit box or safe. +- **Multi-geography strategy** so that a single disaster (fire or flood) doesn’t destroy all copies. + +### Signing Policy and Governance + +If you work within a team or DAO environment that collectively manages a coldkey, implement controls such as a multisig to avoid a single-person compromise. + +How to do this, Polkadot, EVM??? + +### Periodic Security Assessments + +Maintain a secure software environment: +- Keep an eye on newly discovered OS or hardware vulnerabilities. +- Run vulnerability scans on any machine that touches your coldkey. +- Conduct an internal or external penetration test if you operate at scale. + +### Hybrid MLOps Considerations + +In Bittensor, your coldkey might be used to stake and then a hotkey is placed in a production environment for machine learning workloads. Ensure there is a clear boundary: The coldkey environment should **never** install or run untrusted ML code from containers, frameworks, or libraries that might exfiltrate secrets. + +### Additional Reading +- [NIST Cybersecurity Framework](https://www.nist.gov/cyberframework) for high-level best practices. +- [OWASP Cryptographic Failures guidance](https://cheatsheetseries.owasp.org/cheatsheets/Cryptographic_Storage_Cheat_Sheet.html) on common pitfalls. +- [SANS Institute’s InfoSec Reading Room](https://www.sans.org/white-papers/) for practical articles on secure system administration. +- [Polkadot Wiki on Account Security](https://wiki.polkadot.network/docs/learn-accounts#security) (much is relevant to Substrate-based networks like Bittensor). + +In short, you should approach coldkey management as if you were operating a high-value, mission-critical service. By isolating your coldkey from everyday operations, encrypting your keys, using hardware security when possible, and employing rigorous operational hygiene, you greatly reduce your risk. While this might be more complex to set up initially, it pays dividends in security, allowing you to hold and stake TAO with confidence. + + +## Hotkey workstation security + +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. + +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. + +### Secrets managements + +Bittensor miners must handle hotkeys in MLOps pipeline. what are best practices? E.g., mount hotkeys with secrets management solutions like [HashiCorp Vault](https://www.vaultproject.io/), [AWS Secrets Manager](https://aws.amazon.com/secrets-manager/), [Azure Key Vault](https://azure.microsoft.com/en-us/products/key-vault/), or [GCP Secret Manager](https://cloud.google.com/secret-manager) can store your hotkey material. + +### Monitoring and Logging + +What does robust monitoring look like for a miner/validator? e.g.: +- **Track on-chain activity** associated with your hotkey. If you see suspicious transactions (e.g., attempts to re-register on multiple subnets unexpectedly, or large stake changes), investigate immediately. +- **System-level logs**: Keep track of who accessed the server and when. Monitor for suspicious processes or memory usage that might indicate a compromise. +- **API-level logs**: If you run a validator or miner software stack, ensure you log errors, warnings, and out-of-range behaviors in detail. Attackers might attempt to manipulate your node’s behavior or exploit vulnerabilities in the code. + +### Key Lifecycle Management +In many MLOps pipelines, code is deployed continuously. This can create a risk that your hotkey secrets are baked into images or environment variables. Instead: +- Use ephemeral secret injection (CI/CD pipelines like GitLab or GitHub Actions allow storing secrets and injecting them at runtime). +- Periodically rotate hotkeys. You should have something in place to rotate in case of compromise, but you should also probably rotate hotkeys periodically if they are online. + +Should you archive your old hotkeys? if they are attached to a coldkey you still own probably/maybe? what are the implciations, they still bear your identity... + +### Minimizing Attack Surface in ML Workloads +Because Bittensor nodes often run deep learning frameworks (like PyTorch or TensorFlow) to serve inference, that software stack can be large and complex, increasing the attack surface. Strategies to reduce risk: +- Keep your Python environment or Docker images updated with the latest patches. +- Avoid installing unnecessary packages that might contain vulnerabilities. +- 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. + +### Dealing With Potential Compromise + +If you detect or suspect a hotkey compromise... + +let the community know somehow? + +### Team Collaboration + +In some Bittensor setups, a small group or an organization might manage a pool of validators/miners. How do you manage permissions over keys within your org? probably you should have a good strategy though... + + From 06f1f914793a1977347051723bcdc9dd98d2210a Mon Sep 17 00:00:00 2001 From: Michael Trestman Date: Tue, 4 Mar 2025 10:33:26 -0800 Subject: [PATCH 20/23] wip --- docs/btcli-permissions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/btcli-permissions.md b/docs/btcli-permissions.md index aeb39bbf..812dc18a 100644 --- a/docs/btcli-permissions.md +++ b/docs/btcli-permissions.md @@ -18,7 +18,7 @@ See also the `btcli` permissions guides for specific Bittensor personas: Other resources: - [Wallets, Coldkeys and Hotkeys in Bittensor](./getting-started/wallets) - +- [Coldkey and Hotkey Workstation Security](./getting-started/coldkey-hotkey-security) ## Requirements for `btcli` functions From 9fc7c688c9820a3230fcf30380ae5430f6ac8363 Mon Sep 17 00:00:00 2001 From: Michael Trestman Date: Tue, 4 Mar 2025 10:44:04 -0800 Subject: [PATCH 21/23] wip --- docs/btcli-permissions.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/btcli-permissions.md b/docs/btcli-permissions.md index 812dc18a..c4941f0a 100644 --- a/docs/btcli-permissions.md +++ b/docs/btcli-permissions.md @@ -92,12 +92,12 @@ These commands don't require any permissions to run, but you'll run these comman - **Coldkey workstation**: Contains coldkey in the `wallet_path`. For any coldkey associated with mainnet TAO, this should only be done on a secure workstation. :::tip coldkey workstation security - ... + See [Coldkey workstation security](./getting-started/coldkey-hotkey-security#coldkey-workstation-security) ::: - **Hotkey workstation**: Can include servers used for mining or validation. Contains only hotkeys in the `wallet_path` in the `btcli config`. Compromised hotkeys can damage your reputation if they are used to maliciously submit false weights (if you are a validator), or register and submit crappy work ??? if you are a miner, which can be costly. However, ownership of TAO or alpha stake can only be transferred with a coldkey. :::tip hotkey workstation security - ... + See [Hotkey workstation security](./getting-started/coldkey-hotkey-security#hotkey-workstation-security) :::
From 23c16a2d062e89b4431e2eece6a333ea81d85a48 Mon Sep 17 00:00:00 2001 From: Michael Trestman Date: Wed, 5 Mar 2025 09:47:38 -0800 Subject: [PATCH 22/23] wip --- .../coldkey-hotkey-security.md | 3 +- docs/miners/miners-btcli-guide.md | 54 +++++++++++++++---- docs/validators/validators-btcli-guide.md | 4 ++ 3 files changed, 49 insertions(+), 12 deletions(-) diff --git a/docs/getting-started/coldkey-hotkey-security.md b/docs/getting-started/coldkey-hotkey-security.md index 93b7646a..fd3eb73e 100644 --- a/docs/getting-started/coldkey-hotkey-security.md +++ b/docs/getting-started/coldkey-hotkey-security.md @@ -19,9 +19,10 @@ Treat your coldkey as the ultimate authority over your Bittensor wallet. A compr The first principle is to isolate coldkey operations from day-to-day or internet-exposed systems. This often means using a dedicated, air-gapped machine or at least a workstation that is minimally connected to the internet, and has only highly trusted software installed to minimize the risk of malware or keyloggers intercepting your coldkey or recovery seed phrase. -### Coldkeys do not mine +:::tip Coldkeys do not mine 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. +::: ### Air-gapped machines diff --git a/docs/miners/miners-btcli-guide.md b/docs/miners/miners-btcli-guide.md index e0c5192a..dafe96aa 100644 --- a/docs/miners/miners-btcli-guide.md +++ b/docs/miners/miners-btcli-guide.md @@ -4,23 +4,55 @@ title: "Miner's Guide to `BTCLI`" # Miner's Guide to `BTCLI` -Miners run processes that serve or forward inference requests on the network. They register with the chain using a **hotkey** to obtain a UID for the subnet(s) in which they operate. In addition, they must use a coldkey to manage their TAO and any alpha currencies, essentially perforoming all the functions of stakers. +This page discusses `btcli` security and usage considerations specifically for Bittensor miners. For general coverage of `btcli` security and usage considerations across persona, see: [Bittensor CLI: Permissions Guide](../btcli-permissions) -This page discusses btcli stuff specifically for Miners. For general coverage of BTCLI and permissions stuff, see: [Bittensor CLI: Permissions Guide](../btcli-permissions) +Miners in Bittensor work hard to produce digital commondities. To securely serve these commodities to validators, miners use their registered hotkey to sign requests. Miners must also manage their own TAO and alpha stake (to exit the emissions that accure to them), and hence should familiarize themselves with staking operations. -Hotkeys and coldkeys are different yada yada... +**Overview of miner operations by workstation/env:** -Miners primarily rely on **hotkeys** for daily operations. The **coldkey** is only needed when you need to create or fund that hotkey, or if you want to stake additional TAO or pay the burn for certain registrations. +Unpermissioned workstation (public keys only): +- Check balances +- Monitor emissions and other metagraph info +- Check subnet alpha prices across Bittensor + +Coldkey workstation: +- Create/import coldkey +- Create hotkeys +- Manage TAO and alpha stake +- Transfer/rotate TAO and alpha stake in case of key compromise +- Rotate hotkeys in case of compromise +- Register a hotkey to mine on a subnet + +Hotkey workstation: +- import/provision hotkey +- serve w axon + +See: + +- [Wallets, Coldkeys and Hotkeys in Bittensor](../getting-started/wallets) +- [Coldkey and Hotkey Workstation Security](../getting-started/coldkey-hotkey-security) +- [Staking/Delegation Overview](../staking-and-delegation/delegation) +- [Staker's Guide to `BTCLI`](../staking-and-delegation/stakers-btcli-guide) + + +Miners primarily rely on **hotkeys** for daily operations. The **coldkey** is only needed when you need to create or fund that hotkey, or if you want to stake additional TAO or pay the burn for registrations. Hotkey creation can be done on a secure machine (paired with your coldkey). **However, day-to-day mining** is done with the hotkey in a less secure environment (the “mining rig” or server), since it needs to be online to serve inference requests. -Coldkey operations should be performed in a secure environments... +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. + +Coldkey operations should be performed in a secure environments, 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. + +See [Coldkey and Hotkey Workstation Security](../getting-started/coldkey-hotkey-security). + +:::tip Coldkeys do not mine + +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. +::: + +## `btcli` commands for miners: -**Additional Commands most relevant to miners:** +`btcli wallet balance` and `btcli wallet overview`: Might be used to check the hotkey’s on-chain state or small balances. Suitable for low-sec on permissionless (public key only) workstation. -- **Hotkey management**: -- `btcli wallet new-hotkey` / `btcli wallet regen-hotkey`: Creation/regeneration of hotkeys. Typically do these on a secure machine (paired to your coldkey), then transfer the hotkey file or mnemonic to the mining machine. -- `btcli wallet balance` and `btcli wallet overview`: Might be used to check the hotkey’s on-chain state or small balances. (Hotkey on a less secure machine is lower risk, but still treat it with caution.) +`btcli wallet new-hotkey` , `btcli subnets pow-register`, `btcli subnets pow_register`, `btcli subnets register`, `btcli wallet regen-hotkey`: Create and register a hotkey on a secure coldkey workstation (since this requires the coldkey), then transfer the hotkey file or mnemonic to the mining workstation. -_ **Subnet registration**: -- `btcli subnets pow-register`, `btcli subnets pow_register`, `btcli subnets register`: Miner uses these to register themselves on the subnet, typically from a machine with the hotkey. **However,** the associated transaction cost must come from the coldkey. So you either sign it with your coldkey (secure environment) or set up a valid signature flow. The **registration** associates the hotkey with a miner UID on the subnet. diff --git a/docs/validators/validators-btcli-guide.md b/docs/validators/validators-btcli-guide.md index d261457c..c1cabc1e 100644 --- a/docs/validators/validators-btcli-guide.md +++ b/docs/validators/validators-btcli-guide.md @@ -4,6 +4,10 @@ title: "Validator's Guide to `BTCLI`" # Validator's Guide to `BTCLI` +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. + + + Validators evaluate miner performance, and post their evaluations to the blockchain. This page discusses btcli stuff specifically for Validators. For general coverage of BTCLI and permissions stuff, see: [Bittensor CLI: Permissions Guide](../btcli-permissions) From 61e9f2d28f1645f465408bf085c8d483130e1617 Mon Sep 17 00:00:00 2001 From: Michael Trestman Date: Wed, 5 Mar 2025 10:15:05 -0800 Subject: [PATCH 23/23] wip --- .../coldkey-hotkey-security.md | 6 ++- docs/miners/miners-btcli-guide.md | 50 ++++++++++++------- 2 files changed, 37 insertions(+), 19 deletions(-) diff --git a/docs/getting-started/coldkey-hotkey-security.md b/docs/getting-started/coldkey-hotkey-security.md index fd3eb73e..585fe8b9 100644 --- a/docs/getting-started/coldkey-hotkey-security.md +++ b/docs/getting-started/coldkey-hotkey-security.md @@ -13,7 +13,11 @@ See also: ## Coldkey workstation security -Treat your coldkey as the ultimate authority over your Bittensor wallet. A compromised coldkey allows an attacker holder to transfer (steal) your TAO, redelegate your stakes, or take other actions that can’t be reversed. Because of these high stakes, many best practices from both cryptocurrency storage and modern DevOps/MLOps environments apply here. Prioritize confidentiality and integrity over convenience when handling a coldkey. +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. A stolen coldkey allows an attacker holder to transfer (steal) your TAO, redelegate your stakes, or take other actions that can’t be reversed. + +Conversely, there is no way to recover... + +Because of these high stakes, many best practices from both cryptocurrency storage and modern DevOps/MLOps environments apply here. Prioritize confidentiality and integrity over convenience when handling coldkeys. ### Isolation of coldkey operations diff --git a/docs/miners/miners-btcli-guide.md b/docs/miners/miners-btcli-guide.md index dafe96aa..8713356b 100644 --- a/docs/miners/miners-btcli-guide.md +++ b/docs/miners/miners-btcli-guide.md @@ -4,11 +4,40 @@ title: "Miner's Guide to `BTCLI`" # Miner's Guide to `BTCLI` -This page discusses `btcli` security and usage considerations specifically for Bittensor miners. For general coverage of `btcli` security and usage considerations across persona, see: [Bittensor CLI: Permissions Guide](../btcli-permissions) +This page discusses `btcli` security and usage considerations specifically for Bittensor miners. -Miners in Bittensor work hard to produce digital commondities. To securely serve these commodities to validators, miners use their registered hotkey to sign requests. Miners must also manage their own TAO and alpha stake (to exit the emissions that accure to them), and hence should familiarize themselves with staking operations. +For general coverage of `btcli` security and usage considerations across persona, see: [Bittensor CLI: Permissions Guide](../btcli-permissions) -**Overview of miner operations by workstation/env:** +See also: + +- [Wallets, Coldkeys and Hotkeys in Bittensor](../getting-started/wallets) for an introduction to the authentication technology used in Bittensor. +- [Coldkey and Hotkey Workstation Security](../getting-started/coldkey-hotkey-security) for contrete security details about managing keys material. + + +## Intro + +Miners in Bittensor work to produce digital commondities. To securely serve these commodities to validators, miners use their registered hotkey to sign requests. Therefore, miners primarily rely on **hotkeys** for daily operations. + +The **coldkey** is only needed when you need to create or fund that hotkey, or if you want to stake additional TAO or pay the burn for registrations. + + +Miners must also manage their own TAO and alpha stake (to exit the emissions that accure to them), and hence should familiarize themselves with staking operations. + +See: +- [Staking/Delegation Overview](../staking-and-delegation/delegation) +- [Staker's Guide to `BTCLI`](../staking-and-delegation/stakers-btcli-guide) + + +Hotkey creation can be done on a secure machine (paired with your coldkey). **However, day-to-day mining** is done with the hotkey in a less secure environment (the “mining rig” or server), since it needs to be online to serve inference requests. + +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. + +Coldkey operations should be performed in a secure environments, 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. + +See [Coldkey and Hotkey Workstation Security](../getting-started/coldkey-hotkey-security). + + +## Miner operations by workstation/env: Unpermissioned workstation (public keys only): - Check balances @@ -27,23 +56,8 @@ Hotkey workstation: - import/provision hotkey - serve w axon -See: - -- [Wallets, Coldkeys and Hotkeys in Bittensor](../getting-started/wallets) -- [Coldkey and Hotkey Workstation Security](../getting-started/coldkey-hotkey-security) -- [Staking/Delegation Overview](../staking-and-delegation/delegation) -- [Staker's Guide to `BTCLI`](../staking-and-delegation/stakers-btcli-guide) -Miners primarily rely on **hotkeys** for daily operations. The **coldkey** is only needed when you need to create or fund that hotkey, or if you want to stake additional TAO or pay the burn for registrations. - -Hotkey creation can be done on a secure machine (paired with your coldkey). **However, day-to-day mining** is done with the hotkey in a less secure environment (the “mining rig” or server), since it needs to be online to serve inference requests. - -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. - -Coldkey operations should be performed in a secure environments, 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. - -See [Coldkey and Hotkey Workstation Security](../getting-started/coldkey-hotkey-security). :::tip Coldkeys do not mine