Run a validator

Overview

This guide explains how to run a validator TON node with MyTonCtrl from scratch.

Step 1: Prepare environment

1.1 Maintain costs and expenses

• 200 TON per month on the validator hot wallet for its operational transactions.
• Validator deposit stake 700 000 TON ~ 4 000 000 TON.
• 100 TB/month traffic at a peak load.

1.2 Minimal hardware requirements

• 16-core CPU (for example, Intel Xeon E-2388G or equivalent)
• 128 GB RAM
• 2 × 1.92 TB NVMe SSD, each with 250,000+ read IOPS and 83,000+ write IOPS
• 1 Gbit/s network connectivity
• Fixed (static) public IP address

1.3 Software requirements

• Ubuntu 22.04 LTS or 24.04 LTS
• Python 3.10 or higher
• Clang 16.0.0 or higher

# Check Ubuntu version
cat /etc/os-release

# Check Python version
python3 --version

# Check Clang version
clang --version

1.4 Port forwarding for validator

Configure the network on the server according to the following:

• All outgoing connections are allowed.
• A static external IP address.
• One UDP port open for incoming connections.

1.5 Follow network announcements

Subscribe and follow the instructions provided for validators with Telegram channels.

1.6 Prepare validator user

Prepare and log in a user for the validator.

1. Create a non-root user

   # Create a non-root validator user
   sudo adduser <USERNAME>
   sudo usermod -aG sudo <USERNAME>

2. Switch to it by reconnecting to the server via ssh

   #reconnect as the new user
   exit
   ssh <USERNAME>@<SERVER_IP>

1.7 Benchmark server performance

Before installing, verify that the server meets performance requirements. Inadequate disk or network performance is the most common cause of validator instability.

Network latency

Check latency to TON beacon nodes. Expect approximately 50 milliseconds to the nearest beacon and up to 300 milliseconds to the farthest:

ping beacon-eu-01.toncenter.com -c 6
ping beacon-apac-01.toncenter.com -c 6

Disk IOPS

Install fio and run a random read/write benchmark:

sudo apt install -y fio
fio --randrepeat=1 --ioengine=libaio --max-jobs=16 --direct=1 --gtod_reduce=1 --name=test --bs=4k --iodepth=64 --readwrite=randrw --rwmixread=75 --size=10G --filename=/tmp/bench
rm /tmp/bench

Run the benchmark on the same disk where validator data will be stored (/var/ton-work/). If /tmp is on a different filesystem, replace /tmp/bench with a path on the target drive.

Minimum acceptable results:

Network bandwidth

Verify network throughput with speedtest-cli:

sudo apt install -y speedtest-cli
speedtest-cli

Ensure download and upload speeds meet the 1 Gbit/s requirement.

1.8 Harden server security

SSH hardening

Apply the following SSH configuration changes in /etc/ssh/sshd_config:

• Enable key-based authentication and disable password login:

PasswordAuthentication no
PubkeyAuthentication yes

• Disable root login:

PermitRootLogin no

• Change the default SSH port:

Port <SSH_PORT>

<SSH_PORT> — a non-default port number (for example, 2222).

• Restrict SSH access to specific IP addresses using the Match Address directive:

Match Address <ALLOWED_IP>
  AllowUsers <USERNAME>

Restart the SSH service after changes:

sudo systemctl restart sshd

Firewall configuration

Enable the firewall and allow only the SSH port. The validator UDP port is added after installation in step 2.5.

sudo ufw allow <SSH_PORT>/tcp
sudo ufw enable
sudo ufw status

Additional security measures

• Use a unique, strong password for the root user.

• Set a GRUB bootloader password to prevent unauthorized boot modifications.

• Enable Fail2ban for SSH brute-force protection:

  sudo apt install -y fail2ban
  sudo systemctl enable fail2ban
  sudo systemctl start fail2ban

• Configure two-factor authentication for SSH using libpam-google-authenticator or a similar PAM module.

Encrypt sensitive directories (optional)

For additional protection, store validator keys and configuration on an encrypted partition. Create an encrypted volume and symlink the backup directories from it.

Step 2: Validator node installation

2.1 Download validator installer (MyTonCtrl)

Run:

wget https://raw.githubusercontent.com/ton-blockchain/mytonctrl/master/scripts/install.sh

2.2 Run validator installation

Run the validator installation. Installation takes approximately 20 minutes:

sudo bash install.sh -m single-nominator -n mainnet

sudo bash install.sh -m single-nominator -n testnet

2.3 Verify status results

Launch MyTonCtrl with the command mytonctrl. Then, check synchronization using the status command:

mytonctrl
MyTonCtrl> status

Verify that the correct modes are enabled:

MyTonCtrl> status_modes

Expected output should show validator and single-nominator as enabled, with all other modes disabled.

2.4 Verify validator's port

Print engine.addr port configuration config.json file:

grep -A5 '"addrs"' -n /var/ton-work/db/config.json | grep '"port"' | head -1

2.5 Check validator's port

Make sure UDP engine.addr port is allowed with the following command:

sudo ufw status

If the port is filtered (absent in allowed), open this port:

sudo ufw allow <PORT_NUMBER>/udp

Then make sure with sudo ufw status.

2.6 Verify node synchronization

Wait until the node is fully synchronized, which takes approximately 3 hours (depending on the network connection). Check the field Local validator initial sync status: x, the value x should become less than 20.

Step 3: Configure validator

When installing, MyTonCtrl automatically creates a validator wallet. Top up and activate (deploy) this wallet so MyTonCtrl can operate the single nominator pool smart contract with it.

3.1 Get validator wallet address

MyTonCtrl> wl

Find the wallet named validator_wallet_001 and its address.

3.2 Back-up validator wallet secret key

Make a backup of the validator wallet secret key:

MyTonCtrl> ew validator_wallet_001

3.3 Explore validator wallet

Explore validator wallet by address with Tonviewer:

3.4 Credit validator wallet

Credit the validator wallet. Ensure that at least 200 TON per month is available in the validator’s wallet to cover operational fees.

3.5 Activate the wallet

Activate (deploy on-chain) validator wallet, run:

MyTonCtrl> aw validator_wallet_001

That also reflects in Tonviewer; the status will be displayed as Active

3.6 Create a pool

Create a single nominator pool for secure stake management. As the owner-address, specify the beneficiary wallet address that will stake the owner's funds and receive rewards.

MyTonCtrl> new_single_pool <pool-name> <owner-address>

3.7 Print pool list

Explore pool addresses using pools_list command:

MyTonCtrl> pools_list

At the moment, the pool hasn't been deployed yet, and Explorer will display this as Nonexist status

3.8 Activate pool

Activate the single pool nominator contract:

MyTonCtrl> activate_single_pool <pool-name>

3.9 Verify activated pool

Make sure the pool becomes activated with pools_list:

MyTonCtrl> pools_list

Blockchain explorer should also display the now-deployed contract with Active status.

3.10 Test deposit to pool

Test deposit to stake workflow. Any user can deposit to the pool via a standard direct TON transfer. Credit decent sum around 10 TON:

3.11 Test withdrawal from pool

Test withdrawal workflow. Only the owner's cold wallet can request a withdrawal. Send a withdrawal request, a message with w comment from owner wallet to the single nominator pool address:

Once the deposit is restored (except 1 TON reserve on the single nominator pool) to the owner's wallet, that means validator are set securely and ready for real stake:

Step 4: Set optimal stake for validator

Top up the single nominator pool with the effective validation stake. In the next elections, MyTonCtrl will automatically use this pool for staking. Aim for a stake that places the validator between positions 200 and 250 in the validator index.

4.1 Retrieve stakes for last two cycles

Check the current validator stakes on tonscan.org/validators and the minimum network stake in the network config.

Retrieve min_stake and max_stake from Validation API for two last cycles.

For example:

"cycle_id" : 1764052744,
"min_stake": 701812111528562,  // ~ 701 812 TON
"max_stake": 2008570202020000, // ~ 2 008 570 TON

"cycle_id" : 1764052744,
"min_stake": 674810775114391,  // ~ 674 811 TON
"max_stake": 2024432325343173, // ~ 2 024 432 TON

4.2 Retrieve stakes boundary values

To cover the approximate expected stake for odd and even cycles, choose the maximum between the two min_stake and the maximum between the two max_stake.

For example:

// largest within 701 812 TON and 674 811 TON
avg_min_stake = 701812

// largest within 2 008 570 TON and 2 024 432 TON
avg_max_stake = 2024432

4.3 Calculate effective stakes

Effective stake for two cycles is a value between the doubled maximum and the minimum average stakes:

avg_min_stake * 2 <= effective_stake <= avg_max_stake * 2

For example:

// twice the average minimum stake
min_expected_effective_stake = 1403624

// twice the average maximum stake
max_expected_effective_stake = 4048864

Then, the effective stake is approximately:

1403624 TON <= effective_stake <= 4048864 TON

4.4 Deposit effective stake

Deposit effective stake to the single nominator pool address.

4.5 Track first cycle progress

In the next election cycle (odd/even), MyTonCtrl will send half of the stake from the single nominator pool. Track this with a blockchain explorer.

4.6 Track second cycle progress

In the next paired election cycle (even/odd), MyTonCtrl will send the second half of the stake from the single nominator pool. Track this with a blockchain explorer.

4.7 Verify entire staking cycle

The reward for the odd validation cycle will be returned to the single nominator pool, combined with the stake. Verify this with a blockchain explorer. A few minutes after the reward is accepted, MyTonCtrl initiates a re-stake of this stake, including the reward.

Legend

1. Stake for odd cycle.
2. Reward for odd cycle.
3. Reinvestment of the odd cycle stake, including the reward in the next odd cycle.

4.8 Switch to daily maintenance

Make sure pair stakes are appropriately circulated, then focus on monitoring validator health and updates.

Step 5: Maintain validator

5.1 Fund the validator hot wallet

Keep at least 200 TON on the validator hot wallet. This balance covers operational fees for approximately one month.

To check the current balance:

MyTonCtrl> wl

5.2 Top up the single nominator pool

Before sending funds to the pool:

• Verify that the pool address is correct and uses the bounceable format.
• Confirm that the pool smart contract is still active and not frozen. A pool can become frozen if the entire balance is consumed by storage fees between creation and funding.
• Follow the test deposit and withdrawal procedure before depositing the full stake.

If the pool does not pick up the deposit automatically, push it manually:

MyTonCtrl> mg validator_wallet_001 <POOL_ADDRESS> 5

<POOL_ADDRESS> — the bounceable address of the single nominator pool.

5.3 Withdraw funds from the pool

Only the owner wallet can withdraw funds. Follow the test withdrawal procedure using the same method.

5.4 Follow the TON announcements channel

Follow the @tonstatus channel, turn on notifications, and be prepared for urgent updates if needed.

5.5 Organize validator backup

Back up the following paths to an encrypted, off-site location:

• /var/ton-work/db/config.json
• /var/ton-work/db/keyring
• /var/ton-work/keys
• /usr/local/bin/mytoncore (includes wallet files such as validator_wallet_001.pk and validator_wallet_001.addr)

Alternatively, use the built-in MyTonCtrl backup:

MyTonCtrl> create_backup

5.6 Set up alerting

Set up alerting in MyTonCtrl to get a notification of critical issues with the validator. For more information, see MyTonCtrl private alerting bot or check MyTonCtrl public alerting bot.

5.7 Set up monitoring

Set up monitoring dashboards for RAM, disk, network, CPU usage, and other metrics.

• For on-chain validator metrics, use the ton-validators-metrics system.
• For system-level metrics, integrate Prometheus with node_exporter with MyTonCtrl.
• For technical assistance, contact @mytonctrl_help_bot.

5.8 Monitor the efficiency

Set up dashboards to monitor validators using the APIs provided below.

1. Track penalized validators on each round with @tonstatus_notifications.
2. Use Validation API to obtain information about current and past validation rounds (cycles) - including the timing of rounds, which validators participated, their stakes, and more. Information regarding current and past elections for each validation round is also available.
3. Use this API to obtain information about the efficiency of validators over time.

Workflow

1. Check ADNL address of the validator:

   MyTonCtrl> status

2. To the API, provide the ADNL address of the validator along with a time interval (from_ts, to_ts). For accurate results, choose a sufficient interval, such as 18 hours ago to the present moment.

3. Retrieve the result. If the efficiency percentage is below 90%, the validator is malfunctioning.

4. The validator must actively participate in validation and use the same ADNL address throughout the specified time period. For example, if a validator contributes to validation every second round, indicate the intervals during which they participated. Failing to do so may result in an inaccurate underestimate. This requirement applies not only to masterchain validators (with an index < 100) but also to other validators (with an index > 100).

5.9 Learn slashing policy

If a validator processes less than 90% of the expected blocks during a validation round, they will be fined 101 TON.

Learn more about the slashing policy.

5.10 Maintain validator

Stay vigilant on updates, monitor health status, and efficiency stability with dashboards.

Verify

After completing the setup, confirm the validator is operating correctly:

MyTonCtrl> status

Check the following indicators:

Confirm that the validator participates in elections and recovers stakes on time by monitoring the pool balance in a blockchain explorer.

Confirm that the validator participates in elections and recovers stakes on time by checking the pool balance in a blockchain explorer. For greater observability, set up the monitoring of various validator metrics.

Troubleshoot common issues

Node is not synchronizing

• Verify that the validator UDP port is open: sudo ufw status.
• Check network connectivity to beacon nodes: ping beacon-eu-01.toncenter.com -c 6.
• Ensure disk IOPS meet minimum requirements. Re-run the benchmark.
• Check service logs: journalctl -u validator -f.

Validator efficiency is below 90%

• Confirm the node is fully synchronized (Local validator out of sync < 20).
• Check disk performance. Slow storage is the most common cause of low efficiency.
• Verify that no other resource-intensive processes compete for CPU or RAM.
• Review hardware against minimum requirements.

Pool is not participating in elections

• Confirm that the pool is activated: MyTonCtrl> pools_list should show Active status.
• Verify the pool has sufficient balance for at least one cycle: balance > min_stake.
• Check that single-nominator mode is enabled: MyTonCtrl> status_modes.
• Ensure the validator wallet has enough TON for operational fees.

Stake was not returned after a validation cycle

• Wait for the full cycle to complete. Stake recovery is not immediate.
• Check the elector contract status using a blockchain explorer.
• Contact @mytonctrl_help_bot if the stake is not returned after the cycle ends.

Pool contract is frozen

A pool contract may freeze if its entire balance is consumed by storage fees. This happens when too much time passes between pool creation and funding. Ensure you fund the pool promptly after activation.

Support

Contact technical support @mytonctrl_help_bot. This bot is for validators only and will not assist with questions for regular nodes.