Join Testnet Subnet

Requirements

• Linux Environment

  • If on Windows 10-11, follow the WSL documentation

• Python 3.10 or higher

---

Install

git clone https://github.com/hypertensor-blockchain/subnet-template.git
cd subnet-template
python -m venv .venv
source .venv/bin/activate
pip install .
touch .env

Copy and paste the .env.example variables to the newly generated .env file. The main variable required to run the subnet node in this documentation is the DEV_RPC variable.

---

Run in DEBUG Mode (Optional)

Configure your logger and set the debug level to DEBUG to show the debug messages.

This is an optional step meant for debugging the subnet template and the P2P daemon.

export SUBNET_LOGLEVEL=DEBUG

---

In the following, we'll have to manage all of the unique keys for each node deployed:

Copy and paste the following somewhere:

Fill this out as you go along each step as a reference for the later steps.

You can use a .txt file in the following, but ensure not to use a .txt file with markdown because it will produce hidden characters; most command interfaces will include them and break CLI commands.

1. Coldkey

   1. Address: <address>

   2. Private key: <private key>

2. Hotkey

   1. Address: <address>

   2. Private key: <private key>

3. Peer ID

   1. Address: <address>

   2. Path of peer ID private key: <path>

4. Client Peer ID

   1. Address: <address>

   2. Path of client peer ID private key: <path>

5. Bootnode Peer ID

   1. Address: <address>

   2. Path of bootnode peer ID private key: <path>

6. Public IP: <public ip>

7. Port: <port>

---

For each command, you can run <command> --help for information.

---

1. Generate Coldkey and Hotkey

Once both keys are generated, it will output the mnemonic phrase, private key, and address. Store the information in a safe place.

Generate Coldkey

You can also use your coldkey generated by your wallet instead of the CLI.

generate-key --words 12

Save the coldkey private key in a safe space to be used later when registering the node on-chain.

Generate Hotkey

generate-key --words 12

Save the hotkey private key in a safe space to be used later when starting the subnet node.

---

2. Generate Private Keys

Generate 3 private keys for your peer IDs: the main peer ID, the bootnode peer ID, and the client peer ID. This will automatically generate 3 private key files that you will see in the root directory.

Save all 3 peer IDs in the logs in a safe place for later steps.

If running multiple nodes on a single server, ensure all paths are unique.

keygen \
--path main-node01.key \
--bootstrap_path bootnode-node01.key \
--client_path client-node01.key \
--key_type ed25519

---

3. Fund Keys

Visit the Discord faucet and fund both the coldkey and hotkey.

It is suggested to fund the coldkey from the faucet and send 1 TENSOR to the hotkey from the coldkey via the wallet on the explorer. The hotkey is used for consensus, and while running consensus does not have block fees, all wallets are required to have a minimum of 0.0000000000000005 TENSOR to be a live account. By sending the hotkey 1 TENSOR, you will accomplish this requirement.

The coldkey will need at least 100 TENSOR to stake on registration, plus a dynamic burn fee. The faucet will give 500 TENSOR for each request and should be sufficient. If not, contact us on Discord.

1. Use the faucet to fund the coldkey

2. Send 1 TENSOR from the coldkey to the hotkey, or use the faucet (faucet may have a cooldown, if so, use the wallet)

---

4. Register Subnet Node

Register the subnet node on-chain and retrieve your subnet node ID. Put the subnet node ID somewhere to be used for later steps.

Run register-node --help or visit subnet/subnet_cli/node/register.py to view the full list of available arguments.

Before running:

• Know what your coldkey and hotkey are

• Know what subnet ID you're registering to

• Know your peer IDs

• Have the coldkey private key ready

register-node \
--subnet_id ADD SUBNET ID HERE \
--hotkey ADD HOTKEY ADDRESS HERE \
--peer_id ADD MAIN PEER ID HERE \
--bootnode_peer_id ADD BOOTNODE PEER ID HERE \
--client_peer_id ADD CLIENT PEER ID HERE \
--delegate_reward_rate 0.125 \
--stake_to_be_added 100.00 \
--max_burn_amount 100.00 \
--private_key ADD PRIVATE KEY OF COLDKEY HERE

In production, the subnet node should never use the coldkeys private key here. The node should be registered using the CLI (coming soon).

---

5. Run Node

We suggest using a terminal multiplexer or similar of your choosing, such as tmux or pm2.

To successfully join the subnet, the node must wait one full epoch (the node will be considered registered at the end of the following epoch in which it was registered) before joining as the subnet's proof-of-stake mechanism will fail because the node is not yet considered registered on-chain until one full epoch has passed. For example, if registered on epoch 100, the node is considered registered on epoch 101. The nodes start_epoch is the epoch after the one the node calls the registration extrinsic. To verify the start_epoch, see the Stats website or visit the explorer (Chain State > Network > RegisteredSubnetNodesData and input the subnet ID and subnet node ID.)

During testnet, each epoch is approximately 10 minutes.

Before running:

• Get the server's IP you're running the node from

• Ensure you have no firewalls blocking connections

• Choose and open a port

  • Replace 31330 with the port of your choosing in all 4 locations

• Have your subnet node ID

• Have your main identity path generated in the Generate Private Keys step

subnet-server-mock \
--host_maddrs /ip4/0.0.0.0/tcp/31330 /ip4/0.0.0.0/udp/31330/quic \
--announce_maddrs /ip4/YOUR SERVER PUBLIC IP/tcp/31330 /ip4/YOUR SERVER PUBLIC IP/udp/31330/quic \
--identity_path main-node01.key \
--subnet_id ADD SUBNET ID HERE \
--subnet_node_id ADD SUBNET NODE ID \
--private_key ADD PRIVATE KEY OF HOTKEY HERE \
--initial_peers /ip4/13.59.169.172/tcp/31330/p2p/12D3KooWAj2ARm4eDZ836FoEigv2ygZtBnrSKnZv11XhmkrPCBnT /ip4/13.59.169.172/udp/31330/quic/p2p/12D3KooWAj2ARm4eDZ836FoEigv2ygZtBnrSKnZv11XhmkrPCBnT

If connecting to a bootnode fails, there is a 20 second cooldown. For each failed attempt, you cannot connect to the subnet for at least 20 seconds.

Once run, you will see many logs, including:

[INFO] Initializing PoS - proof-of-stake
[INFO] This server is accessible directly
[INFO] About to run DHT
...
[INFO] About to begin consensus

If you do not see This server is accessible directly (otherwise it will log that you're running a relay server), the server either has one of the following issues:

• Firewall is not accepting connections

• The public IP argument is incorrect

• Port is closed for incoming and or outgoing connections

If you cannot resolve this issue, continue running the node as a relay node.

How to resolve network issues:

• Ensure that your Internet provider gives you a public IP address

• Choose a specific port for the subnet template server, for example, 31330

• If you have a firewall or NAT, configure it to allow incoming connections to the chosen TCP port

• Start the server and ensure it logs This server is accessible directly

Keep this running forever.

---

Run Multiple Nodes

Test the scalability of the Subnet Template by running multiple nodes from a single server.

Repeat steps 1-5 for each node, using a separate command prompt for each.