From b32ce1a096cdd70f56726956a6082e5a7511eaf4 Mon Sep 17 00:00:00 2001 From: michael trestman Date: Tue, 9 Sep 2025 11:33:11 -0700 Subject: [PATCH] wip --- docs/miners/autostaking.md | 194 +++++++++++++++++++++++++++++++++++++ docs/miners/index.md | 6 ++ 2 files changed, 200 insertions(+) create mode 100644 docs/miners/autostaking.md diff --git a/docs/miners/autostaking.md b/docs/miners/autostaking.md new file mode 100644 index 0000000000..71c29cb3e2 --- /dev/null +++ b/docs/miners/autostaking.md @@ -0,0 +1,194 @@ +--- +title: "Auto Staking for Miners" +--- + +# Auto Staking for Miners + +Auto staking allows miners to automatically stake their mining income to a validator of their choice, streamlining the process of compound staking without manual intervention. + +## Overview + +The auto staking feature enables miners to set a destination validator where their mining emissions will be automatically staked. This eliminates the need for manual staking operations and ensures that mining rewards are continuously reinvested into the network. + +## How Auto Staking Works + +When auto staking is enabled: + +1. **Mining Income**: As a miner earns emissions from your subnet participation +2. **Automatic Staking**: These emissions are automatically staked to your chosen validator +3. **Compound Growth**: Your stake grows automatically without manual intervention +4. **Validator Selection**: You choose which validator receives your auto-staked TAO + +## Setting Up Auto Staking + +### Prerequisites + +- A coldkey +- A target hotkey to receive the auto-staked TAO (can be any hotkey, including the miner's own hotkey) + + +### Configuration + +Auto staking is configured through the `set_coldkey_auto_stake_hotkey` extrinsic. This function allows a coldkey to designate a hotkey where all future mining rewards will be automatically staked. + +**Extrinsic Details:** +- **Function**: `set_coldkey_auto_stake_hotkey` +- **Call Index**: 114 +- **Parameters**: + - `origin`: The coldkey signature + - `hotkey`: The target hotkey account ID for auto-staking +- **Weight**: ~5.17M + 0 reads + 1 write +- **Payment**: No (no transaction fee required) + +Source: [`subtensor/pallets/subtensor/src/macros/dispatches.rs:2023-2035`](https://github.com/opentensor/subtensor/blob/main/pallets/subtensor/src/macros/dispatches.rs#L2023-L2035) + +The auto staking feature is implemented in the [Subtensor runtime](https://github.com/opentensor/subtensor/pull/2008) and stores the destination in the `AutoStakeDestination` storage map. + +**Storage Definition:** +```rust +#[pallet::storage] // --- MAP ( cold ) --> hot | Returns the hotkey a coldkey will autostake to with mining rewards. +pub type AutoStakeDestination = + StorageMap<_, Blake2_128Concat, T::AccountId, T::AccountId, OptionQuery>; +``` + +Source: [`subtensor/pallets/subtensor/src/lib.rs:1086-1088`](https://github.com/opentensor/subtensor/blob/main/pallets/subtensor/src/lib.rs#L1086-L1088) + +### How It Works + +1. **Coldkey Sets Destination**: The coldkey calls `set_coldkey_auto_stake_hotkey` with the target hotkey +2. **Storage Update**: The `AutoStakeDestination` storage map is updated with `coldkey -> hotkey` mapping +3. **Mining Rewards**: When mining incentives are distributed, the system checks for an auto-stake destination +4. **Automatic Staking**: If a destination exists, rewards are staked to that hotkey instead of the original miner hotkey + +### Checking Auto Staking Status + +You can check your auto staking configuration by querying the `AutoStakeDestination` storage map for your coldkey. + +## Benefits of Auto Staking + +### For Miners + +- **Automated Compound Growth**: Mining rewards are automatically reinvested +- **Reduced Manual Operations**: No need to manually stake earnings +- **Consistent Staking**: Ensures regular staking without forgetting or delays +- **Validator Support**: Helps support your chosen validator's operations + +### For Validators + +- **Predictable Staking**: Receives regular staking from auto-staking miners +- **Network Stability**: Contributes to consistent validator stake levels +- **Reduced Friction**: Miners are more likely to stake when it's automated + +## Important Considerations + +### Validator Selection + +Choose your auto-staking destination carefully: + +- **Validator Performance**: Select validators with good track records +- **Subnet Alignment**: Consider validators that align with your subnet interests +- **Network Health**: Support validators that contribute to network stability + +### Monitoring + +Even with auto staking enabled, you should: + +- **Monitor Validator Performance**: Ensure your chosen validator remains active and performs well +- **Check Staking Status**: Periodically verify that auto staking is working correctly +- **Review Emissions**: Track your mining emissions and staking growth + +### Disabling Auto Staking + +You can disable auto staking by calling `set_coldkey_auto_stake_hotkey` with the same hotkey as the miner (effectively setting it to stake to itself), or by removing the entry from the `AutoStakeDestination` storage map through a runtime upgrade or direct storage manipulation. + +## Technical Details + +### Implementation + +Auto staking is implemented in the [Subtensor runtime](https://github.com/opentensor/subtensor/pull/2008) with the following key components: + +1. **Storage**: `AutoStakeDestination` storage map that maps coldkey to hotkey +2. **Extrinsic**: `set_coldkey_auto_stake_hotkey` function (call index 114) +3. **Logic**: Modified `run_coinbase.rs` to check for auto-stake destination during incentive distribution + +**Code Flow:** +```rust +// In run_coinbase.rs +let owner: T::AccountId = Owner::::get(&hotkey); +let destination = AutoStakeDestination::::get(&owner).unwrap_or(hotkey.clone()); +Self::increase_stake_for_hotkey_and_coldkey_on_subnet( + &destination, // Uses auto-stake destination if set + &owner, + netuid, + incentive, +); +``` + +Source: [`subtensor/pallets/subtensor/src/coinbase/run_coinbase.rs:514-521`](https://github.com/opentensor/subtensor/blob/main/pallets/subtensor/src/coinbase/run_coinbase.rs#L514-L521) + +### Transaction Costs + +The `set_coldkey_auto_stake_hotkey` extrinsic has a weight of approximately 5.17M + 0 database reads + 1 database write, with no transaction fees required. + +### Coldkey Swap Integration + +When a coldkey is swapped, the auto-stake destination is automatically transferred to the new coldkey, ensuring continuity of auto-staking functionality. + +```rust +// In swap_coldkey.rs +if let Some(old_auto_stake_hotkey) = AutoStakeDestination::::get(old_coldkey) { + AutoStakeDestination::::remove(old_coldkey); + AutoStakeDestination::::insert(new_coldkey, old_auto_stake_hotkey); +} +``` + +Source: [`subtensor/pallets/subtensor/src/swap/swap_coldkey.rs:181-184`](https://github.com/opentensor/subtensor/blob/main/pallets/subtensor/src/swap/swap_coldkey.rs#L181-L184) + +## Best Practices + +### For Miners + +1. **Start Small**: Begin with a portion of your mining income to test the system +2. **Choose Reliable Validators**: Select validators with consistent performance +3. **Monitor Regularly**: Check your auto staking status and validator performance +4. **Keep Backup Plans**: Have manual staking as a backup option + +### For Validators + +1. **Maintain Performance**: Keep your validator running smoothly to retain auto-staking miners +2. **Communicate Changes**: Inform miners of any planned validator changes +3. **Monitor Staking**: Track incoming auto-staked TAO from miners + +## Troubleshooting + +### Common Issues + +**Auto staking not working:** +- Verify your `AutoStakeDestination` storage map entry is correctly set +- Check that your target hotkey is valid and owned by the same coldkey +- Ensure sufficient TAO balance for transaction fees +- Verify the extrinsic call was successful + +**Target hotkey becomes invalid:** +- Auto staking will continue to the set destination even if the hotkey becomes inactive +- Update the destination by calling `set_coldkey_auto_stake_hotkey` with a new target + +**Insufficient balance:** +- The `set_coldkey_auto_stake_hotkey` extrinsic requires no transaction fees, so balance is not an issue +- Check your mining emissions are being received and distributed + +### Getting Help + +If you encounter issues with auto staking: + +1. Review the [Subtensor runtime implementation](https://github.com/opentensor/subtensor/pull/2008) +2. Check validator status on [TAO.app](https://tao.app) +3. Join the Bittensor community for support + +## Related Topics + +- [Mining in Bittensor](./index) - Overview of mining operations +- [Staking and Delegation](../staking-and-delegation/delegation) - General staking information +- [Validator Selection](../validators/validator-selection) - Choosing validators +- [Wallet Management](../keys/wallets) - Managing your keys and TAO +- [Chain Extrinsics](../navigating-subtensor/chain-extrinsics) - Working with blockchain transactions diff --git a/docs/miners/index.md b/docs/miners/index.md index 2d9f82d57d..1d55a0137e 100644 --- a/docs/miners/index.md +++ b/docs/miners/index.md @@ -131,6 +131,12 @@ style={{width: 990}} Emissions may not always appear as a smooth curve. Emission might only update at the end of tempo periods, or subnet validators might do more frequent internal updates. For example, a validator might detect new miners and refresh every 100 blocks. ::: +## Auto Staking + +Miners can enable auto staking to automatically stake their mining income to a validator of their choice. This feature streamlines compound staking by eliminating the need for manual staking operations. + +See [Auto Staking for Miners](./autostaking) for detailed information on setting up and managing auto staking. + ## Moving a subnet miner to a different machine Once your subnet miner has begun mining, you can move it to a different machine, but proceed with caution.