Tockchain Testnet Guide for Node Operators

Join the Tockchain public testnet and gain early access to the infrastructure powering the next generation of stablecoins

Introduction

Welcome to the Tockchain Public Testnet!

Project Tockchain is a research initiative for a standalone Layer 1 blockchain with native Qubic integration. If our research proves successful, Tockchain will serve as the foundation for Valis Stablecoins. VUSD, our first stablecoin, will be issued on both Qubic and Tockchain.

This guide will walk you through the steps to set up and run your own node on the Tockchain testnet.

If you would prefer to participate as a user instead of running a node, check out the “Tockchain Testnet Guide for Users” for instructions.

By running a node, you will contribute to the network’s resilience and performance at scale.

Become a Node Operator

Ready to join the Tockchain testnet as a node operator? Follow these steps:

1. Review This Guide: Ensure you meet the knowledge, hardware, software, and connectivity requirements outlined in this guide.
2. Join the Valis Discord: Start by joining the Valis Discord.
3. Send your Application: Submit the Valis Collaboration Form.
4. Await Approval: Once your application is approved, you’ll receive the “Qualification Operator” role on the Valis Discord, unlocking private channels. You’ll also get a Discord message with a link to your personalized “Collaborator Dashboard”.
5. Verify Your Profiles: In the Collaborator Dashboard, confirm that your “Personal Info” and “Node Operator” profiles are correct and up to date.
6. Register Your Node: From the Collaborator Dashboard, select “Register a New Node” and provide the required details. To whitelist your node, we only need your node address and IP. However, full node details are required for testnet participation.
7. Await Approval: After your node registration is approved, your node will appear in your Collaborator Dashboard, where you can update its details. Stay tuned to the #op-qualification-testnet channel on the Valis Discord for announcements on the Qualification Testnet launch date and binary release.
8. Setup Your Node: Follow this guide to configure and run your node on the Qualification Testnet. Upon successful qualification, your node will be eligible for the next Core Testnet.

Unix Basics for Node Operators

Learn the Basic Unix Commands

You’ll use a Unix-based server (like Linux). Don’t worry if you’re new. We’ll guide you!

New to Unix? Don’t worry, here’s a quick guide. These basics will help you set up your node:

<aside> ❓

Tip: Stuck? Try adding --help to the command (e.g., ./vcli --help) or ask in the #op-testnet_qualification channel on the Valis Discord.

</aside>

<aside> ⚠️

In code blocks, text like <password0> or <address0> is highlighted in a different color and means “replace this with your value” (e.g., “MySecurePass123” for a password). Don’t type the < > symbols.

</aside>

Understand the Prompts

The Command Line Interface (CLI) can show two different types of prompts to you:

• The terminal prompt: This is the prompt you first see when you open your Terminal. It looks like user@server:~/valis$ and lets you use Unix commands like ls.
• The binary interactive prompt: This is the prompt you see once you run a binary (e.g., ./vcli). It looks like vcli> (assuming you execute the vcli binary), and lets you use binary-specific commands. When you finish using the binary interactive prompt, type exit or Ctrl+C to return to the terminal prompt.

<aside> ❓

Tip: If you’re unsure where you are, check the prompt. If it shows:

• vcli>, generator>, validator>, or vpoint>: you’re in the interactive prompt for that binary.
• user@server:~/valis$: you’re back in the terminal prompt.

</aside>

For more help when issues arise, see the “FAQ” section at the end of this guide.

Get Help with an AI Assistant

To assist with your setup and answer questions about Unix commands, opening ports, or basic node operation, we recommend using an AI assistant (use Grok for best results). This will save our small team’s time, allowing us to focus on Tockchain-specific support in the #op-testnet_qualification channel on the Valis Discord.

How to Use an AI Assistant:

1. Download the “Tockchain AI Reference”: Visit the “Downloads” section of this guide, download the .md file, and save it to your computer.
2. Upload to an AI: Load the file into Grok 3 (recommended) as a knowledge base. You can do this by uploading the .md file when interacting with the AI or pasting its contents, depending on the platform.
3. Ask Your Questions: Use the AI to ask questions about Unix commands, setup steps, or troubleshooting (e.g., “How do I use chmod +x?” or “What does sudo mean?”).
4. Escalate to Discord if Needed: If the AI can’t resolve your issue or you have questions that are not already answered in the FAQ section, contact us in the #op-testnet_qualification channel on the Valis Discord.

<aside> 📌

Our team is small, and Qsilver is focused on developing the Tockchain protocol. Using an AI for basic questions about Unix commands helps us prioritize support for Tockchain-specific issues. Please ask the AI first. If Grok 3 or similar can’t assist, we’re here to help on the Valis Discord!

</aside>

Steps

Step 1: Understand Testnet Types

Tockchain operates two separate testnets:

• Core Testnet: This the primary testnet network for existing testnet node operators to run and test Tockchain operations.
• Qualification Testnet: A separate testnet for qualifying new node operators, testing their hardware, network, and knowledge before they join the Core Testnet. If you’re a new node operator, you’ll start here.

Step 2: Understand Versioning

2.1. Version Numbers

Tockchain binaries use Semantic Versioning (SemVer) to indicate change compatibility. The version number (X.Y.Z) represents both network and software changes:

• X (Major) – New genesis block: Breaking changes requiring a fresh start, such as new genesis blocks, incompatible API changes, or feature removals.
• Y (Minor) – New testnet: Backward-compatible changes including new testnets with existing genesis blocks, feature additions, performance improvements, or feature deprecation notices.
• Z (Patch) – Changes in the same testnet: Minor updates like bug fixes, rebuilds, dependency updates, performance optimization, logging changes, or whitelist and genesis time adjustments.

graph TD
  A(New genesis block?) -->|Yes| B(Increase X)
  A -->|No| C(New Testnet?)
  C -->|Yes| D(Increase Y)
  C -->|No| E(Increase Z)
 

  style A fill:#1CA0F1,color:#fff,stroke:#1CA0F1
  style B fill:#e4f5fe,color:#000,stroke:#1CA0F1
  style C fill:#1CA0F1,color:#fff,stroke:#1CA0F1
  style D fill:#e4f5fe,color:#000,stroke:#1CA0F1
  style E fill:#e4f5fe,color:#000,stroke:#1CA0F1

2.2. Version Number Examples

Step 3: Understand Testnet Goals

Each testnet has two types of goals: network goals and feature goals.

The next Core Testnet, 3.1, aims to achieve the following:

• Network Goals:
  • Test the performance of our largest network yet, with 17 nodes.
  • Evaluate improvements to both Generator and Validator nodes:
    • Generator: Achieve up to 4x faster processing.
    • Validator: Ensure real-time synchronization, maintaining minimal delay using http://ipaddr/VUSD as fallback, even in the absence of a Generator node.
• Feature Goals:
  • Test ETH and Qubic centralized bridges.
  • Test arbitrage between liquidity pools and order book trading.
  • Test trading with real-world prices.

Step 4: Prepare the Hardware, Software, and Connectivity

Make sure you are using a dedicated server (no VPS), hosted by a provider (not self-hosted), with a static IP (not dynamic), a minimum of 200 Mbps dedicated bandwidth, used exclusively for the Testnet with no other workloads, running Ubuntu 24 or higher, and meeting the minimum hardware requirements.

| --- | --- | --- |

<aside> ❓

</aside>

Step 5: Set Up Your Server Environment

Now that your server’s hardware, software, and connectivity are prepared, you need to set up your server environment. This involves verifying your operating system meets the requirements and ensuring the necessary ports are open for the generator and validator nodes to communicate with other nodes. If these ports are closed, your nodes may fail to sync or tock properly.

5.1. Verify Ubuntu Version

Tockchain Testnets require Ubuntu 24 (other Unix variants must have glibc version 2.38 or later). Verify your server is running the correct version before proceeding:

lsb_release -a

Look for the release number (e.g., 24.04). If you’re not running Ubuntu 24, you’ll need to upgrade your system or set up a new server.

5.2. Open the Required Ports

In order for generator and validator nodes to communicate with other nodes on the testnet, certain ports must be open to facilitate peer communication across the network. The list of required ports will vary per testnet, and any updates for future testnets will be communicated in this section.

For Core Testnet 3.1 (CT3.1), the required ports are: 12001, 9899, 9057, 9999, 31500, and SSH (typically port 22).

Use the following commands to enable the firewall and open the required ports on Ubuntu 24 using ufw (Uncomplicated Firewall):

# Enable and start the firewall
sudo ufw enable
sudo ufw start
sudo ufw reload

# Allow the required ports
sudo ufw allow 12001
sudo ufw allow 9899
sudo ufw allow 9057
sudo ufw allow 9999
sudo ufw allow 31500
sudo ufw allow ssh

<aside> ⚠️

</aside>