Skip to content

Commit 3248514

Browse files
basfromanbasfroman
authored
Merge pull request #3095 from opentensor/docs/roman/add-and-update-md-files
[v10] Update and add new `Markdown` files
2 parents 61879af + 7e89b64 commit 3248514

File tree

4 files changed

+305
-16
lines changed

4 files changed

+305
-16
lines changed

‎README.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -254,6 +254,7 @@ pytest tests/unit_tests
254254
- `BUILD_BINARY` - (`=0` or `=1`) - used with `LOCALNET_SH_PATH` for build or not before start localnet node (for legacy runner);
255255
- `USE_DOCKER` - (`=0` or `=1`) - used if you want to use specific runner to run e2e tests (for docker runner);
256256
- `FAST_BLOCKS` - (`=0` or `=1`) - allows you to run a localnet node in fast or non-fast blocks mode (for both types of runers).
257+
- `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.
257258

258259
#### Using `docker runner` (default for now):
259260
- E2E tests with docker image do not require preliminary compilation

‎docs/migration_guide/BREAKING_CHANGES_v10.md‎

Lines changed: 181 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,181 @@
1+
# Bittensor SDK v10.0.0 - Complete Renaming Reference
2+
3+
## Environment Variables
4+
5+
| Old Name | New Name | Description |
6+
|----------|----------|-------------|
7+
| `BT_CHAIN_ENDPOINT` | `BT_SUBTENSOR_CHAIN_ENDPOINT` | Chain endpoint environment variable |
8+
| `BT_NETWORK` | `BT_SUBTENSOR_NETWORK` | Network environment variable |
9+
10+
## Extrinsic Parameters
11+
12+
### Transfer Functions
13+
| Old Parameter | New Parameter | Context |
14+
|---------------|---------------|---------|
15+
| `dest` | `destination` | `transfer_extrinsic`, `subtensor.transfer` |
16+
17+
### Stake/Unstake Functions
18+
| Old Parameter | New Parameter | Context |
19+
|---------------|---------------|---------------------------------------------------------------------|
20+
| `safe_staking` | `safe_unstaking` | `unstake_extrinsic`, `subtensor.unstake` |
21+
| `safe_staking` | `safe_swapping` | `swap_stake_extrinsic`, `subtensor.swap_stake` |
22+
| `origin_hotkey` | `origin_hotkey_ss58` | `move_stake_extrinsic`, `subtensor.move_stake` |
23+
| `destination_hotkey` | `destination_hotkey_ss58` | `move_stake_extrinsic`, `subtensor.move_stake` |
24+
| `dest` | `destination_ss58` | `subtensor.transfer`, `transfer_extrinsic` and other related calls |
25+
26+
### General Parameter Standardization
27+
| Old Parameter | New Parameter | Context |
28+
|---------------|---------------|---------------------------------------------------------|
29+
| `hotkey` | `hotkey_ss58` | All methods expecting SS58 addresses |
30+
| `coldkey` | `coldkey_ss58` | All methods expecting SS58 addresses |
31+
| `hotkey_ss58_address` | `hotkey_ss58` | All methods |
32+
| `coldkey_ss58_address` | `coldkey_ss58` | All methods |
33+
| `block_number` | `block` | `subtensor.all_subnets` and other methods |
34+
| `destination` | `destination_ss58` | `subtensor.get_transfer_fee` and other related methods |
35+
36+
37+
### Removed and deleted extrinsics:
38+
- All extrinsics with the `_do_*` prefix have been removed. All logic has now been moved to their main extrinsics.
39+
- `bittensor.core.extrinsics.commit_weights` module renamed to `bittensor.core.extrinsics.weights` (consistent naming with async module)
40+
- `set_weights_extrinsic` moved to `bittensor.core.extrinsics.weights`
41+
- `set_root_weights_extrinsic` removed.
42+
43+
## Subtensor Methods
44+
45+
### Method Renames
46+
| Old Method | New Method | Notes |
47+
|------------|------------|-------|
48+
| `subtensor.get_subnets()` | `subtensor.get_all_subnets_netuid()` | More descriptive name |
49+
| `subtensor.get_stake_for_coldkey()` | `subtensor.get_stake_info_for_coldkey()` | Removed duplicate method |
50+
| `subtensor.comit()` | `subtensor.set_commitment()` | Fixed typo, clearer name |
51+
52+
### Parameter Changes
53+
| Method | Old Parameter | New Parameter |
54+
|--------|-----------------------------------|-------------------------------------------------|
55+
| `subtensor.get_transfer_fee()` | `value` | `amount` |
56+
| `subtensor.get_metagraph_info()` | `field_indices` | `selected_indices` |
57+
| All query methods | Various inconsistent orders | Standardized parameter order |
58+
| (async) `get_subnet_validator_permits` and `get_subnet_owner_hotkey` | no `block_hash` and `reuse_block` | added `block_hash` and `reuse_block` parameters |
59+
60+
## Extrinsic Functions
61+
62+
### Function Renames and Moves
63+
| Old Function/Location | New Function/Location |
64+
|-------------------------------------------------------|----------------------------------------------------------------|
65+
| `commit_timelocked_mechanism_weights_extrinsic` | `commit_timelocked_weights_extrinsic` |
66+
| `commit_mechanism_weights_extrinsic` | `commit_weights_extrinsic` |
67+
| `reveal_mechanism_weights_extrinsic` | `reveal_weights_extrinsic` |
68+
| `set_mechanism_weights_extrinsic` | `set_weights_extrinsic` |
69+
| `publish_metadata` | `publish_metadata_extrinsic` |
70+
| `bittensor.core.extrinsics.mechanism.*` | `bittensor.core.extrinsics.weights.*` |
71+
| `bittensor.core.extrinsics.asyncex.mechanism.*` | `bittensor.core.extrinsics.asyncex.weights.*` |
72+
73+
### Merged Functions
74+
| Old Functions | New Unified Function |
75+
|---------------|---------------------|
76+
| `increase_take_extrinsic`, `decrease_take_extrinsic` | `set_take_extrinsic` with `action` parameter |
77+
78+
## Balance Utilities
79+
80+
| Old Function/logic | New Function/logic | Change Type |
81+
|--------------------------------|--------------------------------------|-------------|
82+
| `check_and_convert_to_balance` | `check_balance_amount` | Function rename |
83+
| Warning messages | `BalanceTypeError` exception | Error handling upgrade |
84+
| Warning messages | `BalanceUnitMismatchError` exception | Error handling upgrade |
85+
86+
## Package Structure
87+
88+
### Module Moves
89+
| Old Location | New Location | Notes |
90+
|--------------|---------------------------------------|-------|
91+
| `bittensor.core.subtensor_api` | `bittensor.core.extras.subtensor_api` | Experimental features |
92+
| `bittensor.core.timelock` | `bittensor.core.extras.timelock` | Experimental features |
93+
| `bittensor.core.extrinsics.serving.get_metadata` | `subtensor.get_commitment_metadata` | Method integration |
94+
| `bittensor.core.extrinsics.serving.get_last_bonds_reset` | `subtensor.get_last_bonds_reset` | Method integration |
95+
96+
### Easy Imports Cleanup
97+
| Old Import | New Import | Change |
98+
|-----------------------------------------|------------|--------------------------------|
99+
| `from bittensor import async_subtensor` | `from bittensor import AsyncSubtensor` | Direct class import |
100+
| `from bittensor import axon` | `from bittensor import Axon` | Direct class import |
101+
| `from bittensor import config` | `from bittensor import Config` | Direct class import |
102+
| `from bittensor import dendrite` | `from bittensor import Dendrite` | Direct class import |
103+
| `from bittensor import keyfile` | `from bittensor import Keyfile` | Direct class import |
104+
| `from bittensor import metagraph` | `from bittensor import Metagraph` | Direct class import |
105+
| `from bittensor import wallet` | `from bittensor import Wallet` | Direct class import |
106+
| `from bittensor import subtensor` | `from bittensor import Subtensor` | Direct class import |
107+
| `from bittensor import synapse` | `from bittensor import Synapse` | Direct class import |
108+
| - | `from bittenosor import extrinsics` | Direct subpackage import |
109+
| - | `from bittensor import mock` | Direct subpackage import |
110+
| - | `from bittensor import get_async_subtensor` | Direct factory function import |
111+
NOTE: **References to classes with non-capitalize names are no longer available in Bittensor SDK**
112+
113+
## Mechanisms related changes:
114+
In the next subtensor methods got updated the parameters order with new parameter `mechid`:
115+
- `bonds`
116+
- `get_metagraph_info`
117+
- `get_timelocked_weight_commits`
118+
- `metagraph`
119+
- `weights`
120+
- `commit_weights`
121+
- `reveal_weights`
122+
- `set_weights`
123+
- `bittensor.core.chain_data.metagraph_info.MetagraphInfo` got new attribute `mechid`
124+
125+
## `_mock` parameter in Subtensor classes
126+
127+
| Old Parameter | New Parameter | Context |
128+
|---------------|---------------|-------------------------------|
129+
| `_mock` | `mock` | `Async/Subtensor` constructor |
130+
| Inconsistent parameter order | Standardized order | All async methods |
131+
132+
## Response Types
133+
134+
| Old Return Type | New Return Type | Context |
135+
|-----------------|-----------------|---------|
136+
| `bool` | `ExtrinsicResponse` | All extrinsics |
137+
| `tuple` (bool, str) | `ExtrinsicResponse` | All extrinsics |
138+
| Mixed types | Consistent `ExtrinsicResponse` | All extrinsics |
139+
140+
## Removed Items
141+
142+
### Removed Methods
143+
- `subtensor.get_current_weight_commit_info()`
144+
- `subtensor.get_current_weight_commit_info_v2()`
145+
- `subtensor.set_root_weights_extrinsic()`
146+
- `subtensor.get_stake_for_coldkey()` (use `get_stake_info_for_coldkey` instead)
147+
148+
### Removed Parameters
149+
- `unstake_all` from `unstake_extrinsic` (use `unstake_all_extrinsic` instead)
150+
- `old_balance` from async stake functions
151+
152+
### Removed logic and support
153+
- All `CRv3` related extrinsics and logic.
154+
- `Python 3.9` support.
155+
- `bittensor.utils.version.version_checking`.
156+
- `bittensor.core.config.DefaultConfig`.
157+
158+
## Key Pattern Changes
159+
160+
### Parameter Order Standardization
161+
All extrinsics and related subtensor methods now follow this pattern:
162+
```python
163+
wallet: Wallet,
164+
...
165+
extrinsic specific parameters,
166+
...
167+
period: Optional[int] = None,
168+
raise_error: bool = False,
169+
wait_for_inclusion: bool = True,
170+
wait_for_finalization: bool = True
171+
```
172+
173+
### SS58 Address Naming Convention
174+
- `hotkey`, `coldkey` = Keypair objects
175+
- `hotkey_ss58`, `coldkey_ss58` = SS58 address strings
176+
177+
### Error Handling
178+
- Balance warnings → Explicit exceptions (`BalanceUnitMismatchError` and `BalanceTypeError`).
179+
- 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.
180+
- Extrinsic `bool` returns → Structured `ExtrinsicResponse` objects.
181+
- Extrinsic `tuple[bool, str]` returns → Structured `ExtrinsicResponse` objects.

‎MIGRATION.md‎ renamed to ‎docs/migration_guide/MIGRATION_DRAFT.md‎

Lines changed: 19 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,20 @@
1-
# Plan
1+
## High level overview
2+
To implement the above changes and prepare for the v10 release, the following steps must be taken:
3+
4+
- [x] Create a new branch named SDKv10.
5+
All breaking changes and refactors should be targeted into this branch to isolate them from staging and maintain backward compatibility during development.
6+
- [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.
7+
It must include:
8+
- [x] All change categories (Extrinsics, Subtensor, Metagraph, etc.)
9+
- [x] Per-PR breakdown of what was added, removed, renamed, or refactored.
10+
- [x] Justifications and migration notes for users (if API behavior changed).
11+
12+
- [x] Based on the final `MIGRATION.md`, develop migration documentation for the community.
13+
- [ ] Once complete, merge SDKv10 into staging and release version 10.
14+
15+
<hr>
16+
17+
# Detailed Plan
218

319
## Extrinsics and related
420
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 @@
109125

110126
<hr>
111127

112-
## Implementation
113-
To implement the above changes and prepare for the v10 release, the following steps must be taken:
114-
115-
- [x] Create a new branch named SDKv10.~~
116-
All breaking changes and refactors should be targeted into this branch to isolate them from staging and maintain backward compatibility during development.
117-
- [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.
118-
It must include:
119-
- [x] All change categories (Extrinsics, Subtensor, Metagraph, etc.)
120-
- [x] Per-PR breakdown of what was added, removed, renamed, or refactored.
121-
- [x] Justifications and migration notes for users (if API behavior changed).
122-
123-
- [ ] Based on the final `MIGRATION.md`, develop migration documentation for the community.
124-
- [ ] Once complete, merge SDKv10 into staging and release version 10.
125-
128+
# Step-by-step plan execution
126129

127-
# Migration guide
130+
## Extrinsics refactoring
128131
- [x] `._do_commit_reveal_v3` logic is included in the main code `.commit_timelocked_weights_extrinsic`
129132
- [x] `commit_reveal_version` parameter with default value `4` added to `commit_timelocked_weights_extrinsic`
130133
- [x] `._do_commit_weights` logic is included in the main code `.commit_weights_extrinsic`

0 commit comments

Comments
 (0)