Skip to main content

Running a Full Node

System Administrator Required

For running nodes basic knowledge of Linux/Ubuntu system administration is required.

To install and manage your own node, use the MyTonCtrl open-source tool developed by the TON Foundation. The majority of TON Nodes are reliable and tested by MyTonCtrl.

MyTonCtrl is a console application that is a convenient wrapper for fift, lite-client, and validator-engine-console. It has been specifically developed to streamline wallet, domain, and validator management tasks on the Linux operating system.

We are actively seeking feedback about the installation process. If you have any questions or suggestions, please contact us.

Prerequisites​

We highly recommend installing MyTonCtrl using the supported operating systems:

  • Ubuntu 20.04
  • Ubuntu 22.04
  • Debian 11

Please, non-root user with sudo privileges to install and run MyTonCtrl.

Hardware requirements​

These requirements are for a full node with a validator. If you want to run a full node without a validator (e.g. liteserver), you can use a less powerful machine.

  • 16 cores CPU
  • 128 GB RAM
  • 1TB NVME SSD OR Provisioned 64+k IOPS storage
  • 1 Gbit/s network connectivity
  • public IP address (fixed IP address)
  • 16 TB/month traffic on peak load

You need a machine with a fixed IP address and a high-bandwidth network connection to run a TON Blockchain Full Node.

Typically you'll need a sufficiently powerful server in a data center with good network connectivity, using at least a 1 Gbit/s connection to reliably accommodate peak loads (the average load is expected to be approximately 100 Mbit/s).

Port Forwarding​

All types of nodes require a static external IP address, one UDP port to be forwarded for incoming connections and all outgoing connections to be open - the node uses random ports for new outgoing connections. It's necessarily for the node to be visible to the outside world over the NAT.

It can be done with your network provider or rent a server to run a node.

info

It's possible to find out which UDP port is opened from the netstat -tulpn command.

The TON Foundation recommends the following providers for running a Validator:

GCP (Google Cloud Platform)​

  • Machine Type: n2-standard-16
  • CPU: 32 vCPUs
  • RAM: 128 GB
  • Storage: 1 TB NVMe SSD persistent disk
  • Network: 16 Gbps
  • Public IP: Reserve a static external IP address.
  • Traffic: 16 TB/month

Alibaba Cloud​

  • Instance Type: ecs.g6.4xlarge
  • CPU: 32 vCPUs
  • RAM: 128 GB
  • Storage: 1 TB NVMe SSD disk
  • Network: Up to 10 Gbps
  • Public IP: Bind an Elastic IP for a fixed IP address.
  • Traffic: 16 TB/month

Tencent Cloud​

  • Instance Type: M5.4XLARGE
  • CPU: 32 vCPUs
  • RAM: 128 GB
  • Storage: 1 TB NVMe SSD cloud disk
  • Network: Up to 10 Gbps
  • Public IP: Associate an Elastic IP for a fixed IP address.
  • Traffic: 16 TB/month

Vultr​

  • Instance Type: bare metal Intel E-2388G
  • CPU: 16 Cores / 32 Threads
  • RAM: 128 GB
  • Storage: 1.92TB NVMe SSD
  • Network: 10 Gbps
  • Public IP: Fixed IP address included with instance.
  • Traffic: 16 TB/month

DigitalOcean​

  • Instance Type: general purpose premium Intel
  • CPU: 32 vCPUs
  • RAM: 128 GB
  • Storage: 1TB NVMe SSD
  • Network: 10 Gbps
  • Public IP: Fixed IP address included with instance.
  • Traffic: 16 TB/month

Latitude​

  • Instance Type: c3.medium.x86
  • CPU: 16 Cores / 32 Threads
  • RAM: 128 GB
  • Storage: 1.9TB NVMe SSD
  • Network: 10 Gbps
  • Public IP: Fixed IP address included with instance.
  • Traffic: 16 TB/month
info

Note: Prices, configurations, and availability may vary. It is advisable to always check the official documentation and pricing pages of the respective cloud provider before making any decisions.

How to run a Node? (video)​

Please, check this video step-by-step tutorial to start promptly:

Step-by-step instructions​

Prerequisites​

Login with non-root sudo user​

Login to your server as a non-root user with sudo privileges.

Create and login non-root sudo user​

If you don't have non-root user, you can create this with the following steps steps.

  1. Login as root and create new user:
sudo adduser <username>
  1. Add your user to the sudo group:
sudo usermod -aG sudo <username>
  1. Log into the server as a new user using ssh
ssh <username>@<server-ip-address>

Install the MyTonCtrl​

Download and run the installation script from the non-root user account with sudo privileges. Choose your Linux distributive:

wget https://raw.githubusercontent.com/ton-blockchain/mytonctrl/master/scripts/install.sh
sudo bash install.sh -m full -d
  • -m full - Full node installation mode.
  • -d - mytonctrl will download a dump of the latest blockchain state. This will reduce synchronization time by several times.
  • -c <path> - If you want to use not public liteservers for synchronization. (not required)

Run the mytonctrl​

  1. Run MyTonCtrl console from the local user account used for installation in step 1:

    mytonctrl

  2. Check the MyTonCtrl status using the status command:

    status

The following statuses should be displayed:

  • mytoncore status: Should be in green.
  • Local validator status: Should also be in green.
  • Local validator out of sync: Initially, a large number is displayed. As soon as the newly created validator connects with other validators, the number will be around 250k. As synchronization progresses, this number decreases. When it falls below 20, the validator is synchronized.

Example of the status command output:

status

Make sure you have same output for status

For all nodes type Local Validator status section should appear. Otherwise, check troubleshooting section and check node logs.

Wait until Local validator out of sync becomes less than 20 seconds.

Become a Validator​

View the List of Wallets​

Check out the list of available wallets in the MyTonCtrl console using the wl command:

wl

During the installation of mytonctrl, the validator_wallet_001 wallet is created:

wallet list

Activate the Wallets​

  1. Send the necessary number of coins to the wallet and activate it.

Recently (at the end of 2023), the approximate figures have been a minimum stake of around 340K TON and a maximum of about 1M TON.

Check current stakes with tonscan.com to understand necessary amount of coins.

Read more how maximum and minimum stakes calculated.

  1. Use the vas command to display the history of transfers:
vas
  1. Activate the wallet using the aw command
aw [wallet name]

account history

Your Validator is Now Ready​

mytoncore will automatically join the elections. It divides the wallet balance into two parts and uses them as a stake to participate in the elections. You can also manually set the stake size:

set stake 50000

set stake 50000 — this sets the stake size to 50k coins. If the bet is accepted and our node becomes a validator, the bet can only be withdrawn in the second election (according to the rules of the electorate).

setting stake

Enable Liteserver mode​

When an endpoint is activated in a full node, the node assumes the role of a Liteserver. This node type can field and respond to requests from Lite Clients, allowing for seamless interaction with the TON Blockchain.

Hardware requirements​

Compared to a validator, a liteserver mode requires less resources. However, it is still recommended to use a powerful machine to run a liteserver.

  • at least 16 cores CPU
  • at least 128 GB RAM
  • at least 1TB GB NVMe SSD OR Provisioned 32+k IOPS storage
  • 1 Gbit/s network connectivity
  • 16 TB/month traffic on peak load
  • public IP address (fixed IP address)

Feel free to use cloud providers listed in the Recommended Providers section.

Hetzner and OVH are forbidden to run a validator, but you can use them to run a liteserver:

  • Hetzner: EX101, AX102
  • OVH: RISE-4

Installation of liteserver​

  1. Complete the previous steps to install MyTonCtrl.

  2. Create a config file

MyTonCtrl> installer
MyTonInstaller> clcf

Local config file created: /usr/bin/ton/local.config.json
  1. This file will help you to connect to your liteserver. Copy the config file located on the specified path to your home to save it.
cp /usr/bin/ton/local.config.json ~/config.json

  1. Create an empty config.json file on your local machine.

  2. Copy the content from the console to your local machine config.json file.

cat ~/config.json

Check the firewall settings​

First, verify the Liteserver port specified in your config.json file. This port changes with each new installation of MyTonCtrl. It is located in the port field:

{
  ...
  "liteservers": [
    {
      "ip": 1605600994,
      "port": LITESERVER_PORT
      ...
    }
  ]
}

If you are using a cloud provider, you need to open this port in the firewall settings. For example, if you are using AWS, you need to open the port in the security group.

Below is an example of opening a port in the bare metal server firewall.

Opening a port in the firewall​

We will use the ufw utility (cheatsheet). You can use the one you prefer.

  1. Install ufw if it is not installed:
sudo apt update
sudo apt install ufw
  1. Allow ssh connections:
sudo ufw allow ssh
  1. Allow the port specified in the config.json file:
sudo ufw allow <port>
  1. Check the firewall status. After running this command, you can verify that the rules have been added successfully by checking the UFW status:
sudo ufw status
  1. Enable the firewall:
sudo ufw enable

This way, you can open the port in the firewall settings of your server.

Interaction with Liteserver​

  1. Create an empty project on your machine and paste config.js in the project directory.

  2. Install libraries.

npm i --save ton-core ton-lite-client
  1. Initialize a client and request masterchain info to ensure the liteserver is running.

Change project type to module in your package.json file:

{
    "type": "module"
}

Create index.js file with the following content:

import { LiteSingleEngine } from 'ton-lite-client/dist/engines/single.js'
import { LiteRoundRobinEngine } from 'ton-lite-client/dist/engines/roundRobin.js'
import { LiteClient } from 'ton-lite-client/dist/client.js'
import config from './config.json' assert {type: 'json'};


function intToIP(int ) {
    var part1 = int & 255;
    var part2 = ((int >> 8) & 255);
    var part3 = ((int >> 16) & 255);
    var part4 = ((int >> 24) & 255);

    return part4 + "." + part3 + "." + part2 + "." + part1;
}

let server = config.liteservers[0];

async function main() {
    const engines = [];
    engines.push(new LiteSingleEngine({
        host: `tcp://${intToIP(server.ip)}:${server.port}`,
        publicKey: Buffer.from(server.id.key, 'base64'),
    }));

    const engine = new LiteRoundRobinEngine(engines);
    const client = new LiteClient({ engine });
    const master = await client.getMasterchainInfo()
    console.log('master', master)

}

main()

  1. Now you can interact with your own liteserver.

See also​

Tips & Tricks​

List of available commands​

  • You can use help to get a list of available commands:

Help command

Check the mytonctrl logs​

  • To check mytoncrl logs, open ~/.local/share/mytoncore/mytoncore.log for a local user or /usr/local/bin/mytoncore/mytoncore.log for Root.

logs

Check the node logs​

Check the node logs upon failure:

tail -f /var/ton-work/log.thread*

Troubleshooting​

This section contains answers to the most frequently asked questions about running nodes.

Failed to get account state​

Failed to get account state

This error means that there are issues during search for this account in shard state. Most probably it means that liteserver node is syncing too slow, in particular the Masterchain synchronisation overtook shardchains (Basechain) synchronisation. In this case node knows the recent Masterchain block but can not check account state in recent shardchain block and returns Failed to get account state.

Failed to unpack account state​

Failed to unpack account state

This error means that requested account doesn't exist in current state. That means that this account is simultaneously is not deployed AND has zero balance

Cannot apply external message to current state : External message was not accepted​

Cannot apply external message to current state : External message was not accepted

This error means that contract didn't accepted external message. You need to find exitcode in trace. -13 means that account doesn't have enough TON to accept message (or it requires more than gas_credit). In case of wallet contracts exitcode=33 means wrong seqno (probably seqno data you use is outdatd), exitcode=34 means wrong subwallet_id (for old wallets v1/v2 it means wrong signature), exitcode=35 means that either message is expired (wallets v1-v3) or signature is wrong (v4r2), exitcode=36 means message is expired (usually it means that system time is incorrect).

What does Error 651 mean?​

[Error : 651 : no nodes] indicates that your node cannot locate another node within the TON Blockchain.

Sometimes, this process can take up to 24 hours. However, if you've been receiving this error for several days, that means that your node cannot synchronize via a current network connection.

Solution

You need to check the firewall settings, including any NAT settings if they exist.

It should allow incoming connections on one specific port and outgoing connections from any port.

Validator console is not settings​

If you encounter the Validator console is not settings error, it indicates that you are running MyTonCtrl from a user other than the one you used for the installation.

Solution

Run MyTonCtrl from the user you've installed it (non-root sudo user).

mytonctrl

What does "block is not applied" mean?​

Q: Sometimes we get block is not applied or block is not ready for various requests - is this normal?

A: This is normal, typically this means you tried to retrieve block, which does not reach the node you asked.

Q: If comparative frequency appears, does it mean there is a problem somewhere?

A: No. You need to check "Local validator out of sync" value in mytonctrl. If it's less than 60 seconds, then everything is fine.

But you need to keep in mind that the node is constantly synchronizing. Sometimes, you may try to receive a block that has not reached the node you requested.

You need to repeat the request with a slight delay.

Out of Sync Issue with -d Flag​

If you encounter an issue where the out of sync equals the timestamp after downloading MyTonCtrl with the -d flag, it's possible that the dump wasn't installed correctly (or it's already outdated).

Solution

The recommended solution is to reinstall MyTonCtrl again with the new dump.

If syncing takes an unusually long time, there may have been issues with the dump. Please contact us for assistance.

Please, run mytonctrl from the user you've installed it.

Error command<...> timed out after 3 seconds​

This error means that the local node is not yet synchronized(out of sync lesser then 20 sec) and public nodes are being used. Public nodes do not always respond and end up with a timeout error.

Solution

The solution to the problem is to wait for the local node to synchronize or execute the same command several times before execution.

Status command displays without local node section​

If there is no local node section in the node status, typically this means, something went wrong during installation and the step of creating/assigning a validator wallet was skipped. Also check that the validator wallet is specified.

Check directly the following:

mytonctrl> get validatorWalletName

If validatorWalletName is null then execute the following:

mytonctrl> set validatorWalletName validator_wallet_001

Transfer a Validator on the new Server​

info

Transfer all keys and configs from the old to the working node and start it. In case something goes wrong on the new one, there is still the source where everything is set up.

The best way (while the penalty for temporary non-validation is small, it can be done without interruption):

  1. Perform a clean installation on the new server using mytonctrl, and wait until everything is synchronized.

  2. Stop the mytoncore and validator services on both machines, make backups on the source and on the new one:

  • 2.1 /usr/local/bin/mytoncore/...
  • 2.2 /home/${user}/.local/share/mytoncore/...
  • 2.3 /var/ton-work/db/config.json
  • 2.4 /var/ton-work/db/config.json.backup
  • 2.5 /var/ton-work/db/keyring
  • 2.6 /var/ton-work/keys
  1. Transfer from the source to the new one (replace the contents):
  • 3.1 /usr/local/bin/mytoncore/...
  • 3.2 /home/${user}/.local/share/mytoncore/...
  • 3.3 /var/ton-work/db/config.json
  • 3.4 /var/ton-work/db/keyring
  • 3.5 /var/ton-work/keys

  1. In /var/ton-work/db/config.json edit addrs[0].ip to the current one, which was after installation (can be seen in the backup /ton-work/db/config.json.backup)

  2. Check the permissions on all replaced files

  3. On the new one, start the mytoncore and validator services, check that the node synchronizes and then validates

  4. On the new one, make a backup:

cp var/ton-work/db/config.json var/ton-work/db/config.json.backup