diff --git a/README.md b/README.md index 8e117d2d65..41e53a02dc 100644 --- a/README.md +++ b/README.md @@ -254,6 +254,7 @@ pytest tests/unit_tests - `BUILD_BINARY` - (`=0` or `=1`) - used with `LOCALNET_SH_PATH` for build or not before start localnet node (for legacy runner); - `USE_DOCKER` - (`=0` or `=1`) - used if you want to use specific runner to run e2e tests (for docker runner); - `FAST_BLOCKS` - (`=0` or `=1`) - allows you to run a localnet node in fast or non-fast blocks mode (for both types of runers). +- `SKIP_PULL` - used if you are using a Docker image, but for some reason you want to temporarily limit the logic of updating the image from the repository. #### Using `docker runner` (default for now): - E2E tests with docker image do not require preliminary compilation diff --git a/docs/migration_guide/BREAKING_CHANGES_v10.md b/docs/migration_guide/BREAKING_CHANGES_v10.md new file mode 100644 index 0000000000..ae40b66a6b --- /dev/null +++ b/docs/migration_guide/BREAKING_CHANGES_v10.md @@ -0,0 +1,181 @@ +# Bittensor SDK v10.0.0 - Complete Renaming Reference + +## Environment Variables + +| Old Name | New Name | Description | +|----------|----------|-------------| +| `BT_CHAIN_ENDPOINT` | `BT_SUBTENSOR_CHAIN_ENDPOINT` | Chain endpoint environment variable | +| `BT_NETWORK` | `BT_SUBTENSOR_NETWORK` | Network environment variable | + +## Extrinsic Parameters + +### Transfer Functions +| Old Parameter | New Parameter | Context | +|---------------|---------------|---------| +| `dest` | `destination` | `transfer_extrinsic`, `subtensor.transfer` | + +### Stake/Unstake Functions +| Old Parameter | New Parameter | Context | +|---------------|---------------|---------------------------------------------------------------------| +| `safe_staking` | `safe_unstaking` | `unstake_extrinsic`, `subtensor.unstake` | +| `safe_staking` | `safe_swapping` | `swap_stake_extrinsic`, `subtensor.swap_stake` | +| `origin_hotkey` | `origin_hotkey_ss58` | `move_stake_extrinsic`, `subtensor.move_stake` | +| `destination_hotkey` | `destination_hotkey_ss58` | `move_stake_extrinsic`, `subtensor.move_stake` | +| `dest` | `destination_ss58` | `subtensor.transfer`, `transfer_extrinsic` and other related calls | + +### General Parameter Standardization +| Old Parameter | New Parameter | Context | +|---------------|---------------|---------------------------------------------------------| +| `hotkey` | `hotkey_ss58` | All methods expecting SS58 addresses | +| `coldkey` | `coldkey_ss58` | All methods expecting SS58 addresses | +| `hotkey_ss58_address` | `hotkey_ss58` | All methods | +| `coldkey_ss58_address` | `coldkey_ss58` | All methods | +| `block_number` | `block` | `subtensor.all_subnets` and other methods | +| `destination` | `destination_ss58` | `subtensor.get_transfer_fee` and other related methods | + + +### Removed and deleted extrinsics: +- All extrinsics with the `_do_*` prefix have been removed. All logic has now been moved to their main extrinsics. +- `bittensor.core.extrinsics.commit_weights` module renamed to `bittensor.core.extrinsics.weights` (consistent naming with async module) +- `set_weights_extrinsic` moved to `bittensor.core.extrinsics.weights` +- `set_root_weights_extrinsic` removed. + +## Subtensor Methods + +### Method Renames +| Old Method | New Method | Notes | +|------------|------------|-------| +| `subtensor.get_subnets()` | `subtensor.get_all_subnets_netuid()` | More descriptive name | +| `subtensor.get_stake_for_coldkey()` | `subtensor.get_stake_info_for_coldkey()` | Removed duplicate method | +| `subtensor.comit()` | `subtensor.set_commitment()` | Fixed typo, clearer name | + +### Parameter Changes +| Method | Old Parameter | New Parameter | +|--------|-----------------------------------|-------------------------------------------------| +| `subtensor.get_transfer_fee()` | `value` | `amount` | +| `subtensor.get_metagraph_info()` | `field_indices` | `selected_indices` | +| All query methods | Various inconsistent orders | Standardized parameter order | +| (async) `get_subnet_validator_permits` and `get_subnet_owner_hotkey` | no `block_hash` and `reuse_block` | added `block_hash` and `reuse_block` parameters | + +## Extrinsic Functions + +### Function Renames and Moves +| Old Function/Location | New Function/Location | +|-------------------------------------------------------|----------------------------------------------------------------| +| `commit_timelocked_mechanism_weights_extrinsic` | `commit_timelocked_weights_extrinsic` | +| `commit_mechanism_weights_extrinsic` | `commit_weights_extrinsic` | +| `reveal_mechanism_weights_extrinsic` | `reveal_weights_extrinsic` | +| `set_mechanism_weights_extrinsic` | `set_weights_extrinsic` | +| `publish_metadata` | `publish_metadata_extrinsic` | +| `bittensor.core.extrinsics.mechanism.*` | `bittensor.core.extrinsics.weights.*` | +| `bittensor.core.extrinsics.asyncex.mechanism.*` | `bittensor.core.extrinsics.asyncex.weights.*` | + +### Merged Functions +| Old Functions | New Unified Function | +|---------------|---------------------| +| `increase_take_extrinsic`, `decrease_take_extrinsic` | `set_take_extrinsic` with `action` parameter | + +## Balance Utilities + +| Old Function/logic | New Function/logic | Change Type | +|--------------------------------|--------------------------------------|-------------| +| `check_and_convert_to_balance` | `check_balance_amount` | Function rename | +| Warning messages | `BalanceTypeError` exception | Error handling upgrade | +| Warning messages | `BalanceUnitMismatchError` exception | Error handling upgrade | + +## Package Structure + +### Module Moves +| Old Location | New Location | Notes | +|--------------|---------------------------------------|-------| +| `bittensor.core.subtensor_api` | `bittensor.core.extras.subtensor_api` | Experimental features | +| `bittensor.core.timelock` | `bittensor.core.extras.timelock` | Experimental features | +| `bittensor.core.extrinsics.serving.get_metadata` | `subtensor.get_commitment_metadata` | Method integration | +| `bittensor.core.extrinsics.serving.get_last_bonds_reset` | `subtensor.get_last_bonds_reset` | Method integration | + +### Easy Imports Cleanup +| Old Import | New Import | Change | +|-----------------------------------------|------------|--------------------------------| +| `from bittensor import async_subtensor` | `from bittensor import AsyncSubtensor` | Direct class import | +| `from bittensor import axon` | `from bittensor import Axon` | Direct class import | +| `from bittensor import config` | `from bittensor import Config` | Direct class import | +| `from bittensor import dendrite` | `from bittensor import Dendrite` | Direct class import | +| `from bittensor import keyfile` | `from bittensor import Keyfile` | Direct class import | +| `from bittensor import metagraph` | `from bittensor import Metagraph` | Direct class import | +| `from bittensor import wallet` | `from bittensor import Wallet` | Direct class import | +| `from bittensor import subtensor` | `from bittensor import Subtensor` | Direct class import | +| `from bittensor import synapse` | `from bittensor import Synapse` | Direct class import | +| - | `from bittenosor import extrinsics` | Direct subpackage import | +| - | `from bittensor import mock` | Direct subpackage import | +| - | `from bittensor import get_async_subtensor` | Direct factory function import | +NOTE: **References to classes with non-capitalize names are no longer available in Bittensor SDK** + +## Mechanisms related changes: +In the next subtensor methods got updated the parameters order with new parameter `mechid`: + - `bonds` + - `get_metagraph_info` + - `get_timelocked_weight_commits` + - `metagraph` + - `weights` + - `commit_weights` + - `reveal_weights` + - `set_weights` + - `bittensor.core.chain_data.metagraph_info.MetagraphInfo` got new attribute `mechid` + +## `_mock` parameter in Subtensor classes + +| Old Parameter | New Parameter | Context | +|---------------|---------------|-------------------------------| +| `_mock` | `mock` | `Async/Subtensor` constructor | +| Inconsistent parameter order | Standardized order | All async methods | + +## Response Types + +| Old Return Type | New Return Type | Context | +|-----------------|-----------------|---------| +| `bool` | `ExtrinsicResponse` | All extrinsics | +| `tuple` (bool, str) | `ExtrinsicResponse` | All extrinsics | +| Mixed types | Consistent `ExtrinsicResponse` | All extrinsics | + +## Removed Items + +### Removed Methods +- `subtensor.get_current_weight_commit_info()` +- `subtensor.get_current_weight_commit_info_v2()` +- `subtensor.set_root_weights_extrinsic()` +- `subtensor.get_stake_for_coldkey()` (use `get_stake_info_for_coldkey` instead) + +### Removed Parameters +- `unstake_all` from `unstake_extrinsic` (use `unstake_all_extrinsic` instead) +- `old_balance` from async stake functions + +### Removed logic and support +- All `CRv3` related extrinsics and logic. +- `Python 3.9` support. +- `bittensor.utils.version.version_checking`. +- `bittensor.core.config.DefaultConfig`. + +## Key Pattern Changes + +### Parameter Order Standardization +All extrinsics and related subtensor methods now follow this pattern: +```python +wallet: Wallet, +... +extrinsic specific parameters, +... +period: Optional[int] = None, +raise_error: bool = False, +wait_for_inclusion: bool = True, +wait_for_finalization: bool = True +``` + +### SS58 Address Naming Convention +- `hotkey`, `coldkey` = Keypair objects +- `hotkey_ss58`, `coldkey_ss58` = SS58 address strings + +### Error Handling +- Balance warnings → Explicit exceptions (`BalanceUnitMismatchError` and `BalanceTypeError`). +- Private function `bittensor.utils.balance._check_currencies` raises `BalanceUnitMismatchError` error instead of deprecated warning message. This function is used inside the Balance class to check if units match during various mathematical and logical operations. +- Extrinsic `bool` returns → Structured `ExtrinsicResponse` objects. +- Extrinsic `tuple[bool, str]` returns → Structured `ExtrinsicResponse` objects. \ No newline at end of file diff --git a/MIGRATION.md b/docs/migration_guide/MIGRATION_DRAFT.md similarity index 99% rename from MIGRATION.md rename to docs/migration_guide/MIGRATION_DRAFT.md index 7a3c9173c1..c7e7cf6d25 100644 --- a/MIGRATION.md +++ b/docs/migration_guide/MIGRATION_DRAFT.md @@ -1,4 +1,20 @@ -# Plan +## High level overview +To implement the above changes and prepare for the v10 release, the following steps must be taken: + +- [x] Create a new branch named SDKv10. +All breaking changes and refactors should be targeted into this branch to isolate them from staging and maintain backward compatibility during development. +- [x] Add a `MIGRATION.md` document at the root of the repository and use it as a check list. This file will serve as a changelog and technical reference. +It must include: + - [x] All change categories (Extrinsics, Subtensor, Metagraph, etc.) + - [x] Per-PR breakdown of what was added, removed, renamed, or refactored. + - [x] Justifications and migration notes for users (if API behavior changed). + +- [x] Based on the final `MIGRATION.md`, develop migration documentation for the community. +- [ ] Once complete, merge SDKv10 into staging and release version 10. + +
+ +# Detailed Plan ## Extrinsics and related 1. ✅ Standardize parameter order across all extrinsics and related calls. Pass extrinsic-specific arguments first (e.g., wallet, hotkey, netuid, amount), followed by optional general flags (e.g., wait_for_inclusion, wait_for_finalization) @@ -109,22 +125,9 @@
-## Implementation -To implement the above changes and prepare for the v10 release, the following steps must be taken: - -- [x] Create a new branch named SDKv10.~~ -All breaking changes and refactors should be targeted into this branch to isolate them from staging and maintain backward compatibility during development. -- [x] Add a `MIGRATION.md` document at the root of the repository and use it as a check list. This file will serve as a changelog and technical reference. -It must include: - - [x] All change categories (Extrinsics, Subtensor, Metagraph, etc.) - - [x] Per-PR breakdown of what was added, removed, renamed, or refactored. - - [x] Justifications and migration notes for users (if API behavior changed). - -- [ ] Based on the final `MIGRATION.md`, develop migration documentation for the community. -- [ ] Once complete, merge SDKv10 into staging and release version 10. - +# Step-by-step plan execution -# Migration guide +## Extrinsics refactoring - [x] `._do_commit_reveal_v3` logic is included in the main code `.commit_timelocked_weights_extrinsic` - [x] `commit_reveal_version` parameter with default value `4` added to `commit_timelocked_weights_extrinsic` - [x] `._do_commit_weights` logic is included in the main code `.commit_weights_extrinsic` diff --git a/docs/migration_guide/NEW_FEATURES.md b/docs/migration_guide/NEW_FEATURES.md new file mode 100644 index 0000000000..c658d25195 --- /dev/null +++ b/docs/migration_guide/NEW_FEATURES.md @@ -0,0 +1,104 @@ + +# New in SDKv10 + +### New Classes +- `bittensor.core.types.ExtrinsicResponse` - response for all extrinsics and related calls. +- `bittensor.core.types.BlockInfo` - result avalable from subtensor method `Async/Subtensor.get_block_info()`. Provides comprehensive information about a block in the blockchain, includes the link to block explorer on web service. +- `bittensor.core.errors.BalanceTypeError` - rises when expected amount of balance privided with wrong type data. +- `bittensor.core.errors.BalanceUnitMismatchError` - rises when trying to perform logical or mathematical operations with different currencies (different Balance units). + + NOTE: Please read detailed documentation for these classes in their docstrings. + +### New sub-packages +- `bittensor.core.extrinsics.params` - contains a strict description of the parameters for extrinsics in a single place. +- `bittensor.extras` - contains all additional implementations for the core logic, but which do not affect the overall operation of the Bittensor. These are most often improvements or extensions. + - `bittensor.extras.subtensor_api` + - `bittensor.extras.timelock` + - `bittensor.extras.dev_framework` (read `bittensor/extras/dev_framework/README.md`) + +### New Functions +- `Async/Subtensor.compose_call` +- `Async/Subtensor.validate_extrinsic_params` +- `Async/Subtensor.get_extrinsic_fee` +- `Async/Subtensor.sim_swap` +- `bittensor.utils.hex_to_ss58` +- `bittensor.utils.ss58_to_hex` + NOTE: Please read detailed documentation for these functions in their docstrings. + +### Extrinsics has extra data in response's `data` field: +- `add_stake_extrinsic` +- `add_stake_multiple_extrinsic` +- `burned_register_extrinsic` +- `register_extrinsic` +- `transfer_extrinsic` +- `unstake_extrinsic` +- `unstake_multiple_extrinsic` + +### ArgParser issue +- to turn off args parser across SDK, the local env variable `BT_NO_PARSE_CLI_ARGS` should be set to on of the values: `1`, `true`, `yes`, `on`. This solutions is covering the case when SDK is used in external scripts as a dependency and external script expect the same CLI arguments which is parses by SDK's argparser. + + +### New bihavior + +## All SDK extrinsics and their corresponding Subtensor methods now adhere to a unified parameter standard defined in the subpackage `bittensor.core.extrinsics.params`. +This standard ensures consistency across sync, async, and internal implementations. + +- Each extrinsic is now constructed internally through the `Async/Subtensor.compose_call()` method, which builds a properly encoded `GenericExtrinsic` object based on current runtime metadata. +- Before any extrinsic is created, its parameters are validated by `Async/Subtensor.validate_extrinsic_params()`. +- This validation layer operates against live on-chain metadata obtained from the Substrate runtime, ensuring that argument names, types, and counts strictly match the expected call definition. +- As a result, invalid or outdated calls are detected before submission, providing clear and deterministic error feedback to the user and preventing false or malformed transactions. +- Even if developers create an extrinsic call themselves without using `bittensor.core.extrinsics.params`, but use the `Subtensor.compose_call()` method, the parameters will be validated. + + +## Verbose Logging Behavior in Async and Subtensor Instances + +When initializing either `AsyncSubtensor` or `Subtensor`, the argument `log_verbose=True` now automatically sets the internal logging level to `TRACE`. +This enables the most detailed output available in the SDK, including low-level RPC calls, parameter validation, and extrinsic composition traces — useful for debugging complex chain interactions. +By default, `log_verbose=False`, which keeps the logging level at Warning level without low-level noise. + + +## Stake repated transactions fee + +Now all stake operations fee is calculated with new `SimSwap` logic via `subtensor.sim_swap` method. Detailed logic you can find in class `bittensor.core.chain_data.sim_swap.SimSwapResult`. + + +## Refined Logging Levels and Console Utilities + +Most `logging.info` calls across the SDK have been downgraded to `logging.debug`. +This change significantly reduces unnecessary log noise during normal operation, allowing developers to view clean, high-signal output by default. + +For users who require full visibility into SDK internals — including extrinsic composition, validation, and on-chain responses — enabling the flag `log_verbose=True` automatically raises the logging level to `TRACE`, providing comprehensive diagnostic information. + +In cases where fine-grained or context-specific logging is needed regardless of the global logging configuration, developers can use the utilities from `bittensor.utils.btlogging.console.BittensorConsole`, exposed through the `btlogging.console.*` namespace. +These methods allow explicit control over log output even when global logging is disabled, for example: +```py +btlogging.console.info("Subnet registration started.") +btlogging.console.debug(f"Composed call payload: {payload}") +``` +This design ensures that all logging remains both minimal by default and fully transparent on demand, depending on the user’s debugging needs. + +## Crowdloan implementation +The Crowdloan implementation is expected to be included in the final release of SDKv10. + +## Docstring Refactor and Standardization + +A large-scale refactor has been applied to docstrings across the entire SDK to improve clarity, consistency, and technical accuracy. +Outdated or redundant descriptions have been removed, and all remaining docstrings were rewritten to follow a unified structure and terminology. + +## Resolution of TODOs + +All pending TODO items across the entire codebase have been addressed, resolving long-standing sources of technical debt accumulated over previous SDK versions. +Each TODO was either implemented, removed, or replaced with finalized logic after review. +This cleanup improves overall maintainability, eliminates dead code paths, and ensures that every remaining comment in the SDK reflects active, intentional functionality rather than deferred work. +This update makes the inline documentation more transparent, readable, and aligned with current SDK behavior, ensuring developers can quickly understand method purposes, parameter semantics, and expected return types without referring to external sources. + +## Testing and Development Enhancements + +Beyond general development improvements, significant upgrades were made to the SDK’s testing and CI/CD infrastructure. +The entire pipeline has been refined to include more detailed, scenario-based tests, covering both synchronous and asynchronous functionality. +These improvements enable core developers to deliver updates faster while maintaining a high standard of reliability and regression safety. + +Additionally, a new Development Framework has been introduced, available under `bittensor/extras/dev_framework`. +This framework provides a lightweight environment for quickly deploying local subnets, interacting with neurons, and configuring hyperparameters. +It can also be used to connect and interact with the testnet environment, making it a valuable tool for experimentation, feature validation, and integration testing. +Future releases will continue to expand this framework with additional utilities and automated setup capabilities. \ No newline at end of file