Skip to content

Commit 1966bdc

Browse files
MichaelTrestmanMichael Trestman
MichaelTrestman
and
Michael Trestman
authored
Add Local Development Docs (#557)
* wip * wip * wip * wip * wip --------- Co-authored-by: Michael Trestman <[email protected]>
1 parent 98f4c84 commit 1966bdc

File tree

6 files changed

+531
-3
lines changed

6 files changed

+531
-3
lines changed

‎docs/local-build/create-subnet.md

+174
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,174 @@
1+
---
2+
title: "Create a Subnet (Locally)"
3+
---
4+
5+
# Create a Subnet (Locally)
6+
7+
This page covers creating a subnet on a locally deployed Subtensor blockchain, which is useful for local Bittensor development.
8+
9+
For creating a subnet on Bittensor test and main network, see [Create a Subnet](../subnets/create-a-subnet).
10+
11+
Prerequisites:
12+
- [Deploy a Subtensor chain locally](./deploy)
13+
- [Provision wallets for the sn-creator, miner, and validator users for this tutorial.](./provision-wallets)
14+
15+
## Create subnet (unsuccessful)
16+
17+
To access the handy pre-provisioned development "Alice" account on your local chain, use:
18+
19+
```shell
20+
btcli subnet create \
21+
--subnet-name awesome-first-subnet \
22+
--wallet.name sn-creator \
23+
--subtensor.chain_endpoint ws://127.0.0.1:9945
24+
```
25+
### Trouble shoot
26+
#### Insufficient funds
27+
28+
If you are following this tutorial for the first time, the `subnet create` command will faill with an insufficient balance error.
29+
30+
The coldkey signing the `subnet create` transaction must have a sufficient $\tau$ balance to cover the burn cost of subnet creation, so called because the funds cannot be recovered.
31+
32+
```console
33+
Subnet burn cost: τ 1,000.0000
34+
Your balance of: τ 0.0000 is not enough to burn τ 1,000.0000 to register a subnet.
35+
```
36+
37+
Transfer funds from the Alice account to cover it and try again. Consult `btcli w list` and carefully check the ss58 address of the destination coldkey (in this case, the one with the name `sn-creator`).
38+
39+
```shell
40+
btcli wallet transfer \
41+
--amount 1001 \
42+
--wallet.name alice \
43+
--destination "5C9xw4..." \
44+
--subtensor.chain_endpoint ws://127.0.0.1:9945
45+
```
46+
47+
48+
49+
50+
#### Network Rate Limit Error
51+
52+
If you see a network rate limit error, you may need to adjust the `SubtensorInitialNetworkRateLimit` chain state parameter.
53+
54+
See [Clone and tweak the Subtensor source](./deploy#clone-and-tweak-the-subtensor-source)
55+
56+
### Burn cost
57+
58+
The burn cost for subnet creation is dynamic; it lowers gradually and doubles every time a subnet is created.
59+
60+
:::tip try it live
61+
62+
Check the burn cost to create a subnet on Bittensor main network and test network:
63+
64+
<link rel="stylesheet" href="https://unpkg.com/@antonz/[email protected]/dist/snippet.css" />
65+
<codapi-settings url="https://bittensor-codex.com/v1">
66+
</codapi-settings>
67+
68+
```shell
69+
btcli subnet burn-cost --network finney
70+
```
71+
<codapi-snippet sandbox="python" editor="basic" init-delay="500">
72+
</codapi-snippet>
73+
74+
```shell
75+
btcli subnet burn-cost --network test
76+
```
77+
<codapi-snippet sandbox="python" editor="basic" init-delay="500">
78+
</codapi-snippet>
79+
:::
80+
81+
## Fund your subnet
82+
83+
To remedy your liquidity shortfall, transfer $\tau$ from the Alice account and try again.
84+
85+
1. First, get the ss58 address for the destination wallet for the transfer:
86+
```shell
87+
btcli w list
88+
```
89+
```shell
90+
...
91+
── Coldkey sn-creator ss58_address 5C9xw4gDyu11ocdpWrmhT1sbi4xEHCpzEMsyMA4jGfAZQofQ
92+
└── Hotkey default ss58_address 5GVsCAY6RuSuoAA1E77xsHJ9PjdZJjJrRkNFDxVtRKPnw7TR
93+
```
94+
1. Execute the transfer from alice to the sn-creator wallet
95+
96+
```console
97+
btcli wallet transfer \
98+
--amount 1001 \
99+
--wallet.name alice \
100+
--destination "5GVsCAY6RuSuoAA1E77xsHJ9PjdZJjJrRkNFDxVtRKPnw7TR" \
101+
--subtensor.chain_endpoint ws://127.0.0.1:9945
102+
```
103+
104+
```shell
105+
Do you want to transfer:
106+
amount: τ 1,001.0000
107+
from: alice : 5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKutQY
108+
to: 5GVsCAY6RuSuoAA1E77xsHJ9PjdZJjJrRkNFDxVtRKPnw7TR
109+
for fee: τ 0.0001 [y/n]: y
110+
🌏 📡 Transferring...
111+
```
112+
## Success
113+
Create some subnets.
114+
115+
For example:
116+
117+
```shell
118+
btcli subnet create \
119+
--subnet-name awesome-first-subnet \
120+
--wallet.name sn-creator \
121+
--subtensor.chain_endpoint ws://127.0.0.1:9945
122+
```
123+
```console
124+
Subnet burn cost: τ 1,000.0000
125+
Your balance is: τ 1,001.0000
126+
Do you want to burn τ 1,000.0000 to register a subnet? [y/n]:y
127+
Enter your password:
128+
Decrypting...
129+
🌏 📡 Registering subnet..
130+
```
131+
132+
133+
```shell
134+
btcli subnet create \
135+
--subnet-name awesome-second-subnet \
136+
--wallet.name sn-creator \
137+
--subtensor.chain_endpoint ws://127.0.0.1:9945
138+
```
139+
140+
```console
141+
Subnet burn cost: τ 1,999.9405
142+
▰▱▱▱▱▱▱ 📡Retrieving lock cost from custom...
143+
Your balance is: τ 2,003.0000
144+
Do you want to burn τ 1,999.9405 to register a subnet? [y/n]: Please enter Y or N
145+
Do you want to burn τ 1,999.9405 to register a subnet? [y/n]: y
146+
Enter your password:
147+
Decrypting...
148+
✅ Registered subnetwork with netuid: 3
149+
```
150+
151+
1. List your subnets
152+
153+
```shell
154+
btcli subnet list \
155+
--subtensor.chain_endpoint ws://127.0.0.1:9945
156+
```
157+
```console
158+
Subnets
159+
Network: custom
160+
┃ ┃ Price ┃ Market Cap ┃ ┃ P (τ_in, ┃ Stake ┃ ┃
161+
Netuid ┃ Name ┃ (τ_in/α_in) ┃ (α * Price) ┃ Emission (τ) ┃ α_in) ┃ (α_out) ┃ Supply (α) ┃ Tempo (k/n)
162+
━━━━━━━━╇━━━━━━━━━━━━━╇━━━━━━━━━━━━━╇━━━━━━━━━━━━━╇━━━━━━━━━━━━━━╇━━━━━━━━━━━━━╇━━━━━━━━━━━━━━╇━━━━━━━━━━━━━╇━━━━━━━━━━━━━
163+
0 │ τ root │ 1.0000 τ/Τ │ τ 0.00 │ τ 0.0000 │ -, - │ Τ 0.00 │ 0.00 Τ /21M │ -/-
164+
2 │ β │ 1.0000 τ/β │ τ 1.00k │ τ 0.0000 │ τ 1.00k, │ 0.00 β │ 1.00k β │ 29/360
165+
│ awesome-fi… │ │ │ │ 1.00k β │ │ /21M │
166+
3 │ γ │ 1.0000 τ/γ │ τ 1.00k │ τ 0.0000 │ τ 1.00k, │ 0.00 γ │ 1.00k γ │ 29/360
167+
│ awesome-se… │ │ │ │ 1.00k γ │ │ /21M │
168+
1 │ α apex │ 1.0000 τ/α │ τ 11.00 │ τ 0.0000 │ τ 10.00, │ 1.00 α │ 11.00 α │ 29/100
169+
│ │ │ │ │ 10.00 α │ │ /21M │
170+
────────┼─────────────┼─────────────┼─────────────┼──────────────┼─────────────┼──────────────┼─────────────┼─────────────
171+
4 │ │ τ 3.0 │ │ τ 0.0 │ τ │ │ │
172+
│ │ │ │ │ 2.01k/29.00 │ │ │
173+
│ │ │ │ │ (6931.03%) │ │ │
174+
```

‎docs/local-build/deploy.md

+135
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,135 @@
1+
---
2+
title: "Build and Deploy the Blockchain"
3+
---
4+
5+
# Deploy a Local Bittensor Blockchain Instance
6+
7+
This will will guide the user through deploying a local instance of Subtensor, Bittensor's L1 blockchain. This is useful in general Bittensor develoment, as it gives you more freedom over chain state than when working against mainnet or even testnet. For example, it is much easier to create subnets without having to wait for registration availability.
8+
9+
Each local chain is provisioned with an `alice` account with one million $\tau$.
10+
11+
In the following tutorial, we will also provision several wallets to serve as subnet creator, miner, and validator.
12+
13+
## Prerequisites
14+
15+
- Update your mac or linux workstation using your package manager
16+
- Install [Bittensor SDK](../getting-started/installation) and [BTCLI](../getting-started/install-btcli)
17+
18+
19+
## Build your local Subtensor
20+
### Install Rust/Cargo
21+
22+
To run locally, Substrate requires an up-to-date install of Cargo and Rust
23+
24+
Install from Rust's website:
25+
```shell
26+
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
27+
```
28+
Update your shell's source to include Cargo's path:
29+
30+
```shell
31+
source "$HOME/.cargo/env"
32+
```
33+
34+
### Clone and tweak the Subtensor source
35+
36+
We well clone the source and make a small modification to the state configuration with which the chain is deployed.
37+
38+
Normally, the creation of new subnets is limited to one per day. This is inconvenient for local subnet development, so we will limit this restriction.
39+
40+
41+
42+
1. Fetch the subtensor codebase to your local machine.
43+
44+
```bash
45+
git clone https://github.com/opentensor/subtensor.git
46+
```
47+
48+
1. Open the source file `subtensor/runtime/src/lib.rs` in the your editor of choice, and find where the variable `SubtensorInitialNetworkRateLimit` is set. It is normally configured to 7200, which is the number of blocks per day written to the chain, i.e. the seconds in a day divided by 12, since a Subtensor block is written every twelve seconds.
49+
50+
In otherwords, this setting limits the number of new subnets that can be created to one per day. Let's change the value to 1 (block), so we can create a new subnet every 12 seconds if we want to.
51+
52+
53+
### Setup Rust
54+
55+
This step ensures that you have the nightly toolchain and the WebAssembly (wasm) compilation target. Note that this step will run the Subtensor chain on your terminal directly, hence we advise that you run this as a background process using PM2 or other software.
56+
57+
Update to the nightly version of Rust:
58+
59+
```bash
60+
./subtensor/scripts/init.sh
61+
```
62+
63+
### Build
64+
65+
These steps initialize your local subtensor chain in development mode. These commands will set up and run a local subtensor.
66+
67+
Build the binary with the faucet feature enabled:
68+
69+
```bash
70+
cd subtensor
71+
cargo build -p node-subtensor --profile release
72+
```
73+
74+
### Run
75+
76+
Next, run the localnet script and turn off the attempt to build the binary (as we have already done this above):
77+
78+
```bash
79+
BUILD_BINARY=0 ./scripts/localnet.sh
80+
```
81+
82+
:::info troubleshooting
83+
If you see errors to the effect that the release cannot be found in `targets/fast-blocks`, you may need to move the build artifacts from `targets/release` to `targets/fast-blocks/release`.
84+
:::
85+
86+
87+
## Validate
88+
89+
Ensure your local chain is working by checking the list of subnets.
90+
91+
Note the use of the `--chain_endpoint` flag to target the local chain, rather than, say, test network
92+
93+
```shell
94+
btcli subnet list --subtensor.chain_endpoint ws://127.0.0.1:9945
95+
btcli subnet list --network test
96+
```
97+
98+
```console
99+
Subnets
100+
Network: custom
101+
102+
103+
┃ ┃ Price ┃ Market Cap ┃ ┃ ┃ ┃ ┃
104+
Netuid ┃ Name ┃ (τ_in/α_in) ┃ (α * Price) ┃ Emission (τ) ┃ P (τ_in, α_in) ┃ Stake (α_out) ┃ Supply (α) ┃ Tempo (k/n)
105+
━━━━━━━━╇━━━━━━━━╇━━━━━━━━━━━━━╇━━━━━━━━━━━━━╇━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━╇━━━━━━━━━━━━━
106+
0 │ τ root │ 1.0000 τ/Τ │ τ 0.00 │ τ 0.0000 │ -, - │ Τ 0.00 │ 0.00 Τ /21M │ -/-
107+
1 │ α apex │ 1.0000 τ/α │ τ 11.00 │ τ 0.0000 │ τ 10.00, 10.00 α │ 1.00 α │ 11.00 α /21M │ 77/100
108+
────────┼────────┼─────────────┼─────────────┼──────────────┼────────────────────────┼───────────────┼──────────────┼─────────────
109+
2 │ │ τ 1.0 │ │ τ 0.0 │ τ 10.00/175.00 (5.71%) │ │ │
110+
111+
```
112+
113+
114+
```shell
115+
```
116+
117+
```console
118+
119+
Subnets
120+
Network: test
121+
122+
123+
┃ ┃ Price ┃ Market Cap ┃ ┃ ┃ ┃ ┃
124+
Netuid ┃ Name ┃ (τ_in/α_in) ┃ (α * Price) ┃ Emission (τ) ┃ P (τ_in, α_in) ┃ Stake (α_out) ┃ Supply (α) ┃ Tempo (k/n)
125+
━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━╇━━━━━━━━━━━━━╇━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━
126+
0 │ τ root │ 1.0000 τ/Τ │ τ 5.01m │ τ 0.0000 │ -, - │ Τ 3.10m │ 5.01m Τ /21M │ -/-
127+
277 │ इ muv │ 0.4008 τ/इ │ τ 536.06k │ τ 0.4154 │ τ 199.85k, 498.63k इ │ 838.83k इ │ 1.34m इ /21M │ 39/99
128+
3 │ γ templar │ 0.1534 τ/γ │ τ 219.03k │ τ 0.1690 │ τ 110.74k, 722.13k γ │ 706.14k γ │ 1.43m γ /21M │ 65/99
129+
119 │ Ⲃ vida │ 0.0748 τ/Ⲃ │ τ 94.83k │ τ 0.1321 │ τ 44.77k, 598.65k Ⲃ │ 669.45k Ⲃ │ 1.27m Ⲃ /21M │ 81/99
130+
1 │ α apex │ 0.0587 τ/α │ τ 70.03k │ τ 0.0405 │ τ 30.27k, 515.71k α │ 677.20k α │ 1.19m α /21M │ 63/99
131+
13 │ ν dataverse │ 0.0467 τ/ν │ τ 63.12k │ τ 0.0645 │ τ 26.93k, 576.17k ν │ 774.11k ν │ 1.35m ν /21M │ 75/99
132+
255 │ ዉ ethiopic_wu │ 0.0181 τ/ዉ │ τ 21.94k │ τ 0.0133 │ τ 10.72k, 592.40k ዉ │ 619.73k ዉ │ 1.21m ዉ /21M │ 17/99
133+
134+
...
135+
```

0 commit comments

Comments
 (0)